Aprire file e cartelle con selezione in WinUI

Usa i selettore di file e cartelle di Windows App SDK per consentire agli utenti di esplorare e selezionare file o cartelle nell'app WinUI. Le API di selezione offrono un'esperienza di Windows familiare che consente agli utenti di spostarsi nei percorsi di archiviazione cloud e del dispositivo. Questo articolo illustra come implementare i selettori di file e cartelle, personalizzarne il comportamento e gestire i risultati selezionati nell'app.

Le classi FileOpenPicker e FileSavePicker di Windows App SDK creano una finestra di dialogo di selezione che consente agli utenti di specificare il nome e il percorso di un file da aprire o salvare. La classe FolderPicker consente di selezionare una cartella.

Per informazioni sull'uso di una selezione per salvare i file, vedere Salvare un file con una selezione di Windows App SDK.

API importanti

Questo articolo usa le API seguenti:

• FileOpenPicker
• FolderPicker
• StorageFile

Interfaccia utente di selezione file

Una selezione file visualizza informazioni per orientare gli utenti e offrire un'esperienza coerente durante l'apertura o il salvataggio di file.

Tali informazioni includono:

• Posizione corrente
• Elemento o elementi selezionati dall'utente
• Albero delle posizioni che l'utente può sfogliare. Questi percorsi includono i percorsi del file system, ad esempio la cartella Musica o Download, nonché le app che implementano il contratto di selezione file (ad esempio Fotocamera, Foto e Microsoft OneDrive).

Potrebbe essere disponibile un'app che consente agli utenti di aprire o salvare file. Quando l'utente avvia quell'azione, l'app chiama il selettore di file, che visualizza l'interfaccia utente del selettore di file.

Come funzionano gli strumenti di selezione con l'app

Con una selezione, l'app può accedere, esplorare e salvare file e cartelle nel sistema dell'utente. L'app riceve tali scelte come oggetti PickFileResult e PickFolderResult leggeri, che forniscono il percorso del file o della cartella selezionata.

La selezione usa una singola interfaccia unificata per consentire all'utente di selezionare file e cartelle dal file system o da altre app. I file prelevati da altre app sono come file del file system. In generale, l'app può operare su di essi nello stesso modo degli altri oggetti. Altre app rendono disponibili i file partecipando ai contratti di selezione file.

Ad esempio, puoi chiamare il selettore di file nell'app in modo che l'utente possa aprire un file. Questa azione rende la tua app l'app chiamante. La selezione file interagisce con il sistema e altre app per consentire all'utente di spostarsi e selezionare il file. Quando l'utente sceglie un file, la selezione file restituisce il percorso del file all'app.

Selezionare un file per aprire un esempio

Il codice seguente illustra come usare la classe FileOpenPicker per consentire all'utente di selezionare un singolo file, ad esempio una foto. Il codice imposta le proprietà sul selettore per personalizzarne l'aspetto e il comportamento e quindi mostra lo strumento di selezione all'utente usando il metodo PickSingleFileAsync . Se l'utente seleziona un file, l'app legge il contenuto del file e lo archivia in una variabile.

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

Questo è lo stesso esempio in 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.
}

Selezionare più file per aprire un esempio

È anche possibile consentire all'utente di selezionare più file. Il codice seguente illustra come usare la classe FileOpenPicker per consentire all'utente di selezionare più file, ad esempio le foto. Il processo è lo stesso, ma il metodo PickMultipleFilesAsync restituisce una raccolta di percorsi di file anziché un singolo percorso.

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

Per eseguire la stessa operazione in C++, usare il codice seguente:

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

Selezionare un esempio di cartella

Per selezionare una cartella usando la classe FolderPicker , usare il codice seguente. Questo codice crea una selezione cartelle, la mostra all'utente usando il metodo PickSingleFolderAsync e recupera il percorso della cartella selezionata in un oggetto PickFolderResult . Se l'utente seleziona una cartella, l'app recupera il percorso della cartella e la archivia in una variabile per usarla in un secondo momento.

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

Per eseguire la stessa operazione in C++, usare il codice seguente:

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

Suggerimento

Ogni volta che l'app accede a un file o a una cartella tramite una selezione, aggiungerla all'app FutureAccessList o MostRecentlyUsedList per tenerne traccia usando le API di Windows Runtime (WinRT). Per altre informazioni, vedere Come tenere traccia di file e cartelle usati di recente.

L'interfaccia utente della selezione cartelle è simile alla seguente:

Contenuti correlati

Windows.Storage.Pickers

File, cartelle e librerie con Windows App SDK

Namespace Microsoft.Windows.Storage.Pickers