Compartilhar via

Salvar um arquivo com o seletor do SDK de Aplicativo do Windows no WinUI

Ao criar aplicativos do Windows com o SDK do Aplicativo do Windows, os usuários geralmente precisam salvar arquivos como documentos, imagens ou outros conteúdos em locais específicos em seu dispositivo. O SDK de Aplicativo do Windows fornece a classe FileSavePicker para criar uma interface consistente e amigável que permite que os usuários escolham onde salvar arquivos e como nomeá-los.

Este artigo mostra como implementar um seletor de salvamento de arquivos em seu aplicativo WinUI. Você aprenderá a configurar a aparência e o comportamento do seletor, manipular 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 a salvação dos arquivos pelos usuários:

Uma captura de tela de um seletor de arquivo de salvamento com um nome de arquivo sugerido

Pré-requisitos

Antes de começar, verifique se você tem:

  • Um projeto WinUI configurado com o SDK do Aplicativo do Windows
  • Familiaridade básica com C# e XAML
  • Noções básicas sobre padrões assíncronos/de espera em C#

APIs importantes

As seguintes APIs são usadas neste tópico:

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. Crie, personalize e mostre um objeto seletor de arquivo e salve dados por meio do objeto StorageFile retornado que representa o arquivo escolhido.

  1. Crie e personalize o FileSavePicker. Comece criando um novo objeto FileSavePicker e 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",
};

    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 como a pasta da biblioteca de Documentos, usando o valor DocumentsLibrary do PickerLocationId. Defina SuggestedStartLocation como um local apropriado para o tipo de arquivo que está sendo salvo, por exemplo, Música, Imagens, Vídeos ou Documentos. No local de início, o usuário pode navegar e selecionar outros locais.

    Para poupar o usuário de um pouco de digitação, o exemplo define um SuggestedFileName. O nome do arquivo sugerido deve ser relevante para o arquivo que está sendo salvo. Por exemplo, como o Word, você pode sugerir o nome do arquivo existente se houver um ou a primeira linha de um documento se o usuário estiver salvando um arquivo que ainda não tenha um nome.

    Use a propriedade FileTypeChoices ao especificar os tipos de arquivo aos quais o exemplo dá suporte (documentos do Microsoft Word e arquivos 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 compatíveis com seu aplicativo. Os usuários poderão salvar o arquivo como qualquer um dos tipos de arquivo especificados. 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 .

    Observação

     O seletor de arquivos também usa o tipo de arquivo selecionado no momento para filtrar quais arquivos ele exibe, de modo que somente os tipos de arquivo que correspondem aos tipos de arquivos selecionados sejam exibidos para o usuário.

    O código C++ equivalente para este exemplo é o seguinte:

    #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");

    Observação

      Os objetos FileSavePicker exibem o seletor de arquivos usando o modo de exibição PickerViewMode.List .

  2. Em seguida, vamos mostrar o FileSavePicker e salvar no local do arquivo 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 para 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.";
}

    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á nulle você poderá lidar com esse caso adequadamente, como exibir uma mensagem para o usuário.

    Dica

     Você sempre deve verificar o arquivo salvo para verificar se ele existe e é válido antes de executar qualquer outro processamento. Em seguida, você pode salvar o conteúdo no arquivo conforme apropriado para seu aplicativo. Seu aplicativo deverá fornecer o comportamento apropriado se o arquivo escolhido não for válido.

    Aqui está o equivalente de C++ deste exemplo de C#:

    #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.");
}

Conteúdo relacionado

Windows.Storage.Pickers

Arquivos, pastas e bibliotecas com o SDK do Aplicativo do Windows

PickSaveFileAsync

  • Last updated on