Partilhar via

Salvar um arquivo com o seletor do SDK de aplicativos do Windows na WinUI

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

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:

Uma captura de tela de um seletor de arquivos salvo com um nome de arquivo sugerido

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:

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 de seletor de arquivos e, em seguida, salve dados por meio do objeto StorageFile retornado que representa o arquivo selecionado.

  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",
};

    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, 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 tem um nome.

    Use a propriedade FileTypeChoices ao especificar os tipos de arquivo que o exemplo suporta (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 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 .

    Observação

     O seletor de arquivos também usa o tipo de arquivo selecionado atualmente para filtrar quais arquivos ele exibe, para que apenas os tipos de arquivo que correspondam 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 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á null, e você pode lidar com esse caso adequadamente, como exibir uma mensagem para o usuário.

    Sugestão

     Você deve sempre verificar o arquivo salvo para se certificar de que 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 deve fornecer o comportamento apropriado se o arquivo escolhido não for válido.

    Aqui está o equivalente em 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

Ficheiros, pastas e bibliotecas com o SDK de Aplicações Windows

PickSaveFileAsync

  • Last updated on