Aprire file e cartelle con una selezione

API importanti

• FileOpenPicker
• FolderPicker
• StorageFile

Accedi a file e cartelle permettendo all'utente di interagire con una selezione. È possibile usare le classi FileOpenPicker e FileSavePicker per accedere ai file e FolderPicker per accedere a una cartella.

Nota

 Per un esempio completo, vedere l'Esempio di selezione file.

Nota

in un'app desktop (che includa app WinUI 3) è possibile usare selezioni di file e cartelle da Windows.Storage.Pickers. Tuttavia, se l'app desktop richiede l'elevazione per l'esecuzione, è necessario un approccio diverso perché queste API non sono progettate per essere usate in un'app con privilegi elevati. Per un esempio, vedere FileSavePicker.

Prerequisiti

• Familiarità con la programmazione asincrona per le app UWP (Universal Windows Platform)

  Per informazioni su come scrivere app asincrone in C# o Visual Basic, vedere Chiamare API asincrone in C# o Visual Basic. Per scoprire come scrivere app asincrone in C++, vedere Programmazione asincrona in C++.

• Autorizzazioni di accesso al percorso

  Vedi Autorizzazioni di accesso ai file.

Interfaccia utente di selezione file

Una selezione file visualizza informazioni per favorire l'orientamento degli utenti e offrire loro un'esperienza uniforme per l'apertura o il salvataggio dei file.

Tali informazioni includono:

• Percorso corrente
• Elemento o elementi selezionati dall'utente
• Albero dei percorsi che l'utente può esplorare. I percorsi includono posizioni nel file system, come la cartella Musica o Download, nonché le app che implementano un contratto di selezione file, come Fotocamera, Foto e Microsoft OneDrive.

Un'app per posta elettronica potrebbe visualizzare una selezione file per permettere all'utente di selezionare gli allegati.

Come funzionano le selezioni file

Tramite una selezione, l'app può accedere ai file e alle cartelle, esplorarli e salvarli nel sistema dell'utente. L'app riceve tali selezioni come oggetti StorageFile e StorageFolder, sui quali è possibile poi intervenire.

La selezione usa una singola interfaccia unificata per permettere all'utente di selezionare file e cartelle dal file system o da altre app. I file selezionati dalle altre app sono uguali ai file del file system, in quanto anch'essi vengono restituiti come oggetti StorageFile. In generale, l'app può gestire questi file analogamente agli altri oggetti di questo tipo. Le altre app rendono disponibili i propri file aderendo ai contratti di selezione file. Se si vuole che l'app fornisca file, un percorso di salvataggio o aggiornamenti dei file ad altre app, vedere Integrazione con i contratti di selezione file.

È ad esempio possibile chiamare la selezione file nell'app per consentire all'utente di aprire un file. In questo caso l'app è l'app chiamante. La selezione file interagisce con il sistema e/o le altre app in modo tale che l'utente possa esplorare e selezionare il file. Quando l'utente sceglie un file, la selezione file lo restituisce all'app. Ecco il processo per il caso in cui l'utente sceglie un file da un'app che lo fornisce, ad esempio OneDrive.

Selezionare un singolo file: elenco completo del codice

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
picker.FileTypeFilter.Add(".jpg");
picker.FileTypeFilter.Add(".jpeg");
picker.FileTypeFilter.Add(".png");

Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
if (file != null)
{
    // Application now has read/write access to the picked file
    this.textBlock.Text = "Picked photo: " + file.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

Selezionare un singolo file: istruzioni dettagliate

L'uso di una selezione file comporta la creazione e personalizzazione di un oggetto selezione file e quindi la visualizzazione della selezione file in modo tale che l'utente possa selezionare uno o più elementi.

1. Creare e personalizzare un FileOpenPicker

   var picker = new Windows.Storage.Pickers.FileOpenPicker();
   picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
   picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
   picker.FileTypeFilter.Add(".jpg");
   picker.FileTypeFilter.Add(".jpeg");
   picker.FileTypeFilter.Add(".png");
   

   Impostare le proprietà dell'oggetto selezione file rilevanti per gli utenti e per l'app.

   Questo esempio crea una visualizzazione ricca di immagini in una posizione comoda, dalla quale l'utente può effettuare la propria selezione impostando tre proprietà: ViewMode, SuggestedStartLocatione FileTypeFilter.

   • Impostando ViewMode sul valore di enumerazione ThumbnailPickerViewMode, verrà creata una visualizzazione avanzata grazie all'uso di anteprime delle immagini per rappresentare i file nella selezione file. Eseguire questa operazione per la selezione di file visivi, ad esempio immagini o video. In caso contrario, usare PickerViewMode.List. Un'app per posta elettronica ipotetica con funzionalità Allega immagine o video e Allega documento imposta la ViewMode appropriata per la funzionalità prima di visualizzare la selezione file.

   • Se si imposta SuggestedStartLocation su Immagini usando PickerLocationId.PicturesLibrary, l'utente partirà da una posizione in cui è probabile che siano disponibili immagini. Impostare SuggestedStartLocation su una posizione appropriata per il tipo di file selezionato, ad esempio Musica, Immagini, Video o Documenti. Gli utenti possono spostarsi in altre posizioni dalla posizione iniziale.

   • L'uso di FileTypeFilter per specificare i tipi di file consente di mantenere l'utente concentrato sulla selezione di file pertinenti. Per sostituire i tipi di file precedenti in FileTypeFilter con nuovi tipi di file, usare ReplaceAll invece di Add.

2. Visualizzare la selezione per apertura file

   • Per selezionare un singolo file

     Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
     if (file != null)
     {
         // Application now has read/write access to the picked file
         this.textBlock.Text = "Picked photo: " + file.Name;
     }
     else
     {
         this.textBlock.Text = "Operation cancelled.";
     }
     

   • Per selezionare più file

     var files = await picker.PickMultipleFilesAsync();
     if (files.Count > 0)
     {
         StringBuilder output = new StringBuilder("Picked files:\n");
     
         // Application now has read/write access to the picked file(s)
         foreach (Windows.Storage.StorageFile file in files)
         {
             output.Append(file.Name + "\n");
         }
         this.textBlock.Text = output.ToString();
     }
     else
     {
         this.textBlock.Text = "Operation cancelled.";
     }
     

Selezionare una cartella: elenco completo del codice

var folderPicker = new Windows.Storage.Pickers.FolderPicker();
folderPicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.Desktop;
folderPicker.FileTypeFilter.Add("*");

Windows.Storage.StorageFolder folder = await folderPicker.PickSingleFolderAsync();
if (folder != null)
{
    // Application now has read/write access to all contents in the picked folder
    // (including other sub-folder contents)
    Windows.Storage.AccessCache.StorageApplicationPermissions.
    FutureAccessList.AddOrReplace("PickedFolderToken", folder);
    this.textBlock.Text = "Picked folder: " + folder.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

Suggerimento

Ogni volta che l'app accede a un file o a una cartella tramite una selezione file, aggiungere tale elemento agli elenchi FutureAccessList o MostRecentlyUsedList dell’app per tenerne traccia. Per altre informazioni sull'uso di questi elenchi, vedere Come tenere traccia dei file e delle cartelle usati di recente.

Vedi anche

Windows.Storage.Pickers

File, cartelle e raccolte

Integrazione con contratti di selezione file