Abrir arquivos e pastas com seletores no WinUI

Use os seletores de arquivos e pastas do SDK do Aplicativo Windows 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 locais de armazenamento em nuvem e dispositivos. Este artigo mostra como implementar seletores abertos de arquivos e seletores de pastas, personalizar seu comportamento e lidar com os resultados selecionados em seu aplicativo.

As classes FileOpenPicker e FileSavePicker do SDK do Aplicativo Windows criam uma caixa de diálogo de seletor que permite que os usuários especifiquem o nome e o local de um arquivo para abrir ou salvar. A classe FolderPicker permite que você selecione uma pasta.

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

APIs importantes

Este artigo usa as seguintes APIs:

• FileOpenPicker
• FolderPicker
• StorageFile

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:

• O local atual
• O item ou os itens escolhidos pelo usuário
• Uma árvore de locais para os quais o usuário 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:

Como os seletores funcionam com seu aplicativo

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

O seletor usa uma única interface unificada para permitir que o usuário escolha arquivos e pastas do sistema de arquivos ou de outros aplicativos. Os arquivos escolhidos de outros aplicativos são como arquivos do sistema de arquivos. Em geral, seu aplicativo pode operá-los da mesma maneira que outros objetos. Outros aplicativos disponibilizam arquivos participando de contratos de seletor de arquivos.

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.

Escolher 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 mostra o seletor para o usuário usando o método PickSingleFileAsync . Se o usuário escolher um arquivo, o aplicativo lerá o conteúdo do arquivo e o armazenará 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.
}

Escolher 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 no 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.
}

Escolher 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 a 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 no 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.
}

Dica

Sempre que seu aplicativo acessa um arquivo ou pasta por meio de um seletor, adicione-o ao FutureAccessList ou MostRecentlyUsedList do seu aplicativo para controlar isso usando as APIs do WinRT (Windows Runtime). Para obter mais informações, consulte Como rastrear arquivos e pastas usados recentemente.

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

Conteúdo relacionado

Windows.Storage.Pickers

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

Namespace Microsoft.Windows.Storage.Pickers