Tutorial: Abra ficheiros e pastas com selecionadores no WinUI

Use seletores de ficheiros e pastas do Windows App SDK para permitir que os utilizadores naveguem e selecionem ficheiros ou pastas na sua aplicação WinUI. As APIs de seleção proporcionam uma experiência familiar do Windows que ajuda os utilizadores a navegar pelos seus dispositivos e localizações de armazenamento na 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 Windows App SDK FileOpenPicker e FileSavePicker criam um diálogo de seleção que permite aos utilizadores especificar o nome e a localização de um ficheiro a abrir ou guardar. A classe FolderPicker permite selecionar uma pasta.

Para aprender sobre o uso de um seletor para guardar ficheiros, veja Guardar um ficheiro com um seletor de Windows App SDK.

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:

• A localização atual
• O item ou itens que o usuário seleciona
• Uma árvore de locais pelos quais o utilizador pode navegar. Estas localizações incluem localizações do sistema de ficheiros — como a pasta Música ou Downloads — bem como aplicações que implementam o contrato de seleção de ficheiros (como Câmara, 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, 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.
}

#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.
}

#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.
}

#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.
}

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

Conteúdo relacionado

Windows. Storage.Pickers

Ficheiros, pastas e bibliotecas com Windows App SDK

Microsoft.Windows.Storage.Pickers namespace