Tutorial: Abra ficheiros e pastas com selecionadores no WinUI

Use seletores de ficheiros e pastas do SDK de Aplicações Windows 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 SDK de Aplicações Windows 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 SDK de Aplicações Windows.

Pré-requisitos

• SDK de Aplicações Windows 1.8 ou posterior. As Microsoft.Windows.Storage.Pickers APIs usadas neste artigo foram introduzidas no SDK de Aplicações Windows 1.8. Se o seu projeto visa uma versão anterior, consulte Use WinRT pickers with HWND interop para a abordagem anterior.

APIs importantes

Este artigo usa as seguintes APIs:

• FileOpenPicker
• FolderPicker
• PickFileResult
• PickFolderResult

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 devolve uma coleção de objetos PickFileResult . Cada resultado expõe uma Path propriedade quando precisa do caminho do ficheiro bruto.

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:

Usar seletores WinRT com interoperabilidade com HWND

Se o seu projeto se destina ao SDK de Aplicações Windows 1.7 ou anterior, ou se utilizar as APIs legadas Windows.Storage.Pickers (por exemplo, ao migrar do UWP), tem de inicializar o seletor com um identificador de janela (HWND) antes de o apresentar. Sem este passo, o seletor lança uma exceção ou falha silenciosamente em aplicações de ambiente de trabalho (WinUI 3).

Exemplo de C# (selecionadores WinRT antigos)

// This example assumes you have a reference to your app's main window.
// In a Window class, use 'this'. In a Page, use a stored reference like App.MainWindow.

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.FileTypeFilter.Add(".png");
picker.FileTypeFilter.Add(".jpg");

// Get the window handle (HWND) for the current WinUI 3 window.
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);

// Associate the picker with the window.
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);

var file = await picker.PickSingleFileAsync();
if (file is null)
{
    // The user cancelled the picker.
}

Exemplo de C++/WinRT (seletores WinRT clássicos)

// pch.h
#include <winrt/Windows.Storage.Pickers.h>
#include <microsoft.ui.xaml.window.h>
#include <shobjidl_core.h>

// MainWindow.xaml.cpp — inside a MainWindow member function
Windows::Storage::Pickers::FileOpenPicker picker;
picker.FileTypeFilter().Append(L".png");
picker.FileTypeFilter().Append(L".jpg");

// Get the window handle (HWND) of the current WinUI 3 window.
auto windowNative{ this->m_inner.as<::IWindowNative>() };
HWND hwnd{ 0 };
windowNative->get_WindowHandle(&hwnd);

// Associate the picker with the window.
auto initializeWithWindow{ picker.as<::IInitializeWithWindow>() };
initializeWithWindow->Initialize(hwnd);

auto file{ co_await picker.PickSingleFileAsync() };
if (!file)
{
    // The user cancelled the picker.
}

Para mais informações sobre como recuperar uma maçaneta de janela, veja Recuperar uma maçaneta de janela (HWND).

Conteúdo relacionado

• espaço de nomes Microsoft.Windows.Storage.Pickers
• Guardar um ficheiro utilizando um seletor de ficheiros do SDK de Aplicações Windows
• Ficheiros, pastas e bibliotecas com SDK de Aplicações Windows
• Recuperar um identificador de janela (HWND)
• Chamar APIs de interoperação numa aplicação .NET
• Exibir objetos da interface do usuário do WinRT que dependem de CoreWindow
• Exemplo de seletor de ficheiros WinUI Gallery