Tutorial: Guardar um ficheiro com os seletores do Windows App SDK no WinUI

Ao construir aplicações Windows com o Windows App SDK, os utilizadores muitas vezes precisam de guardar ficheiros como documentos, imagens ou outros conteúdos em locais específicos do seu dispositivo. O Windows App SDK fornece a classe FileSavePicker para criar uma interface consistente e fácil de usar que permite aos utilizadores escolher onde guardar os ficheiros e que nomes lhes devem dar.

Este artigo mostra como implementar um seletor de salvamento de arquivos em seu aplicativo WinUI. Você aprenderá como configurar a aparência e o comportamento do seletor, lidar com a seleção do usuário e salvar o conteúdo no local escolhido.

O seletor de arquivos de salvamento pode ser preenchido com um nome de arquivo sugerido e outras configurações padrão para facilitar que os usuários salvem seus arquivos:

Pré-requisitos

Antes de começar, certifique-se de que:

• Um projeto WinUI configurado com o Windows App SDK
• Familiaridade básica com C# e XAML
• Compreensão dos padrões async/await em C#

APIs importantes

As APIs a seguir são usadas neste tópico:

• FileSavePicker
• StorageFile

Use o FileSavePicker para permitir que os usuários especifiquem o nome e o local onde desejam que seu aplicativo salve um arquivo.

Salvar um documento com FileSavePicker

Use um FileSavePicker para que os usuários possam especificar o nome, o tipo e o local de um arquivo a ser salvo. Criar, personalizar e mostrar um objeto seletor de ficheiros, e depois guardar os dados através do objeto devolvido StorageFile que representa o ficheiro escolhido.

1. Crie e personalize o FileSavePicker. Comece criando um novo objeto FileSavePicker e, em seguida, defina propriedades no objeto para personalizar o seletor de arquivos para seu aplicativo e seus usuários:

    using Microsoft.Windows.Storage.Pickers;
    ...
    var savePicker = new FileSavePicker(this.AppWindow.Id)
    {
        // (Optional) Specify the initial location for the picker. 
        //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
        //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
        SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
        
        // (Optional) specify the default file name. If not specified, use system default.
        SuggestedFileName = "My Document",
    
        // (Optional) Sets the folder that the file save dialog displays when it opens.
        //     If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
        SuggestedFolder = @"C:\MyFiles",
    
        // (Optional) specify the text displayed on the commit button. 
        //     If not specified, the system uses a default label of "Save" (suitably translated).
        CommitButtonText = "Save Document",
    
        // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
        //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
        FileTypeChoices = {
            { "Documents", new List<string> { ".txt", ".doc", ".docx" } }
        },
    
        // (Optional) specify the default file extension (will be appended to SuggestedFileName).
        //      If not specified, no extension will be appended.
        DefaultFileExtension = ".txt",
    };

    #include <winrt/Microsoft.Windows.Storage.Pickers.h>
    using namespace winrt::Microsoft::Windows::Storage::Pickers;
    
    FileSavePicker savePicker(AppWindow().Id());
    
    // (Optional) Specify the initial location for the picker. 
    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
    savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
    
    // (Optional) specify the default file name. If not specified, use system default.
    savePicker.SuggestedFileName(L"NewDocument");
    
    // (Optional) Sets the folder that the file save dialog displays when it opens.
    //     If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
    savePicker.SuggestedFolder = L"C:\\MyFiles",
    
    // (Optional) specify the text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Save" (suitably translated).
    savePicker.CommitButtonText(L"Save Document");
    
    // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
    //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
    savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
    
    // (Optional) specify the default file extension (will be appended to SuggestedFileName).
    //      If not specified, no extension will be appended.
    savePicker.DefaultFileExtension(L".txt");

Este exemplo define seis propriedades: SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices e DefaultFileExtension.

Como o usuário está salvando um documento ou arquivo de texto, o exemplo define o SuggestedStartLocation para a pasta da biblioteca de documentos usando o valor DocumentsLibrary do Enum PickerLocationId . Defina o SuggestedStartLocation para um local apropriado para o tipo de arquivo que está sendo salvo, por exemplo, Música, Imagens, Vídeos ou Documentos. A partir do local de início, o usuário pode navegar e selecionar outros locais.

Para poupar o utilizador de escrever, o exemplo define um SuggestedFileName. O nome de arquivo sugerido deve ser relevante para o arquivo que está sendo salvo. Por exemplo, tal como no Word, pode sugerir o nome do ficheiro existente se houver, ou a primeira linha de um documento se o utilizador estiver a guardar um ficheiro que ainda não tem nome.

Use a propriedade FileTypeChoices ao especificar os tipos de ficheiro que o exemplo suporta (Microsoft Word documentos e ficheiros de texto). Isso garante que o aplicativo possa abrir o arquivo depois que ele for salvo. Verifique se todos os tipos de arquivo especificados são suportados pelo seu aplicativo. Os usuários poderão salvar seus arquivos como qualquer um dos tipos de arquivo que você especificar. Eles também podem alterar o tipo de arquivo selecionando outro dos tipos de arquivo especificados. A primeira opção de tipo de arquivo na lista será selecionada por padrão. Para controlar isso, defina a propriedade DefaultFileExtension .

2. De seguida, mostra o FileSavePicker e guarda na localização do ficheiro escolhido. Exiba o seletor de arquivos chamando PickSaveFileAsync. Depois que o usuário especifica o nome, o tipo de arquivo e o local e confirma salvar o arquivo, PickSaveFileAsync retorna um objeto FilePickResult leve que contém o caminho para o arquivo salvo e o nome do arquivo. Você pode capturar e processar esse arquivo se tiver acesso de leitura e gravação a ele.

    using Microsoft.Windows.Storage.Pickers;
    ...
    var savePicker = new FileSavePicker(this.AppWindow.Id);
    var result = await savePicker.PickSaveFileAsync();
    if (result != null)
    {
        if (!System.IO.File.Exists(result.Path))
        {
            // Create a file and write to it.
            System.IO.File.WriteAllText(result.Path, "Hello world." + Environment.NewLine);
        }
        else
        {
            // Append to the existing file.
            System.IO.File.AppendAllText(result.Path, "Hello again." + Environment.NewLine);
        }
    }
    else
    {
        this.textBlock.Text = "Operation cancelled.";
    }

    #include <winrt/Microsoft.Windows.Storage.Pickers.h>
    #include <fstream>
    #include <string>
    using namespace winrt::Microsoft::Windows::Storage::Pickers;
    
    FileSavePicker savePicker(AppWindow().Id());
    auto result{ co_await savePicker.PickSaveFileAsync() };
    if (result)
    {
        // Check if the file exists.
        if (!std::ifstream(result.Path().c_str()))
        {
            std::ofstream outFile(result.Path().c_str());
            outFile << "Hello world.";
            outFile.close();
        }
        else
        {
            // Append to the existing file.
            std::ofstream outFile(result.Path().c_str(), std::ios::app);
            outFile << "Hello again.";
            outFile.close();
        }
    }
    else
    {
        textBlock().Text(L"Operation cancelled.");
    }

O exemplo verifica se o arquivo existe e cria um novo arquivo ou acrescenta ao arquivo existente. Se o usuário cancelar a operação, o resultado será null, e você pode lidar com esse caso adequadamente, como exibir uma mensagem para o usuário.

Conteúdo relacionado

Windows. Storage.Pickers

Ficheiros, pastas e bibliotecas com Windows App SDK

PickSaveFileAsync