Abrir arquivos e pastas com seletores no WinUI

Use os seletores de arquivos e pastas do SDK do Windows App para permitir que os usuários naveguem e selecionem arquivos ou pastas em seu aplicativo WinUI. As APIs do seletor fornecem uma experiência familiar do Windows que ajuda os usuários a navegar em seus dispositivos e locais de armazenamento em nuvem. Este artigo mostra como implementar seletores de abertura de arquivos e seletores de pastas, personalizar seu comportamento e manipular os resultados selecionados em seu aplicativo.

As classes FileOpenPicker e FileSavePicker do SDK do Windows App criam uma caixa de diálogo de seletor que permite aos usuários especificar o nome e o local de um arquivo para abrir ou salvar. A classe FolderPicker permite selecionar uma pasta.

Para saber mais sobre como usar um seletor para salvar arquivos, consulte Salvar um arquivo com um seletor do SDK de aplicativos Windows.

APIs importantes

Este artigo usa as seguintes APIs:

Interface do usuário do seletor de arquivos

Um seletor de arquivos exibe informações para orientar os usuários e fornecer uma experiência consistente ao abrir ou salvar arquivos.

Essas informações incluem:

A localização atual
O item ou itens que o usuário seleciona
Uma árvore de locais pelos quais o utilizador pode navegar. Esses locais incluem locais do sistema de arquivos, como a pasta Música ou Downloads, bem como aplicativos que implementam o contrato do seletor de arquivos (como Câmera, Fotos e Microsoft OneDrive).

Você pode ter um aplicativo que permite que os usuários abram ou salvem arquivos. Quando o usuário inicia essa ação, seu aplicativo chama o seletor de arquivos, que exibe a interface do usuário do seletor de arquivos:

Captura de ecrã de um seletor de ficheiros aberto com um filtro selecionado para mostrar ficheiros .txt, .pdf, .doc e .docx.

Como os seletores funcionam com seu aplicativo

Com um seletor, seu aplicativo pode acessar, navegar e salvar arquivos e pastas no sistema do usuário. Seu aplicativo recebe essas escolhas como objetos leves PickFileResult e PickFolderResult , que fornecem o caminho para o arquivo ou pasta selecionados.

O seletor usa uma interface única e unificada para permitir que o usuário escolha arquivos e pastas do sistema de arquivos ou de outros aplicativos. Os ficheiros selecionados de outras aplicações são como ficheiros do sistema de ficheiros. Em geral, seu aplicativo pode operar neles da mesma maneira que outros objetos. Outras aplicações disponibilizam ficheiros através da participação em contratos de seletores de ficheiros.

Por exemplo, você pode chamar o seletor de arquivos em seu aplicativo para que o usuário possa abrir um arquivo. Essa ação torna seu aplicativo o aplicativo de chamada. O seletor de arquivos interage com o sistema e outros aplicativos para permitir que o usuário navegue e escolha o arquivo. Quando o usuário escolhe um arquivo, o seletor de arquivos retorna o caminho desse arquivo para seu aplicativo.

Escolha um arquivo para abrir o exemplo

O código a seguir mostra como usar a classe FileOpenPicker para permitir que o usuário escolha um único arquivo, como uma foto. O código define propriedades no seletor para personalizar sua aparência e comportamento e, em seguida, mostra o seletor para o usuário usando o método PickSingleFileAsync . Se o usuário escolher um arquivo, o aplicativo lê o conteúdo do arquivo e o armazena em uma variável.

using Microsoft.Windows.Storage.Pickers;

var openPicker = new FileOpenPicker(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 text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Open" (suitably translated).
    CommitButtonText = "Choose selected files",

    // (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
    FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },

    // (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
    ViewMode = PickerViewMode.List,
};

var result = await openPicker.PickSingleFileAsync();
if (result is not null)
{
    var content = System.IO.File.ReadAllText(result.Path);
}
else
{
    // Add your error handling here.
}

Este é o mesmo exemplo em C++:

#include <winrt/Microsoft.Windows.Storage.Pickers.h>
#include <fstream>
#include <string>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FileOpenPicker openPicker(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.
openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);

// (Optional) specify the text displayed on the commit button. 
//     If not specified, the system uses a default label of "Open" (suitably translated).
openPicker.CommitButtonText(L"Choose selected files");

// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
openPicker.FileTypeFilter().ReplaceAll({ L".txt", L".pdf", L".doc", L".docx" });

// (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
openPicker.ViewMode(PickerViewMode::List);

auto result{ co_await openPicker.PickSingleFileAsync() };
if (result)
{
    std::ifstream fileReader(result.Path().c_str());
    std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
    winrt::hstring hText = winrt::to_hstring(text);
}
else
{
    // Add your error handling here.
}

Escolha vários arquivos para abrir o exemplo

Você também pode permitir que o usuário escolha vários arquivos. O código a seguir mostra como usar a classe FileOpenPicker para permitir que o usuário escolha vários arquivos, como fotos. O processo é o mesmo, mas o método PickMultipleFilesAsync retorna uma coleção de caminhos de arquivo em vez de um único caminho.

using Microsoft.Windows.Storage.Pickers;

var openPicker = new FileOpenPicker(this.AppWindow.Id);

var results = await openPicker.PickMultipleFilesAsync();
if (results.Count > 0)
{
    var pickedFilePaths = results.Select(f => f.Path);
    foreach (var path in pickedFilePaths)
    {
        var content = System.IO.File.ReadAllText(path);
    }
}
else
{
    // Add your error handling here.
}

Para executar a mesma operação em C++, use o seguinte código:

#include <winrt/Microsoft.Windows.Storage.Pickers.h>
#include <fstream>
#include <string>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FileOpenPicker openPicker(this->AppWindow().Id());
auto results{ co_await openPicker.PickMultipleFilesAsync() };
if (results.Size() > 0)
{
    for (auto const& result : results)
    {
        std::ifstream fileReader(result.Path().c_str());
        std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
        winrt::hstring hText = winrt::to_hstring(text);
    }
}
else
{
    // Add your error handling here.
}

Escolha um exemplo de pasta

Para escolher uma pasta usando a classe FolderPicker , use o código a seguir. Esse código cria um seletor de pastas, mostra-o ao usuário usando o método PickSingleFolderAsync e recupera o caminho da pasta selecionada em um objeto PickFolderResult . Se o usuário escolher uma pasta, o aplicativo recuperará o caminho da pasta e o armazenará em uma variável para uso posterior.

using Microsoft.Windows.Storage.Pickers;

var folderPicker = new FolderPicker(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 text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Open" (suitably translated).
    CommitButtonText = "Select Folder",

    // (Optional) specify the view mode of the picker dialog. If not specified, default to List.
    ViewMode = PickerViewMode.List,
};

var result = await folderPicker.PickSingleFolderAsync();

if (result is not null)
{
    var path = result.Path;
}
else
{
    // Add your error handling here.
}

Para executar a mesma operação em C++, use o seguinte código:

#include <winrt/Microsoft.Windows.Storage.Pickers.h>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FolderPicker folderPicker(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.
folderPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);

// (Optional) specify the text displayed on the commit button. 
//     If not specified, the system uses a default label of "Open" (suitably translated).
folderPicker.CommitButtonText(L"Select Folder");

// (Optional) specify the view mode of the picker dialog. If not specified, default to List.
folderPicker.ViewMode(PickerViewMode::List);

auto result{ co_await folderPicker.PickSingleFolderAsync() };
if (result)
{
    auto path{ result.Path() };
}
else
{
    // Add your error handling here.
}

Sugestão

Sempre que seu aplicativo acessar um arquivo ou pasta por meio de um seletor, adicione-o à FutureAccessList ou MostRecentlyUsedList do aplicativo para acompanhá-lo usando as APIs do Tempo de Execução do Windows (WinRT). Para obter mais informações, consulte Como controlar arquivos e pastas usados recentemente.

A interface do usuário do seletor de pastas tem esta aparência:

Captura de ecrã de um seletor de pastas a visualizar a unidade C.