Salvare un file con il selettore di Windows App SDK in WinUI

Quando si compilano app di Windows con Windows App SDK, gli utenti spesso devono salvare file come documenti, immagini o altri contenuti in posizioni specifiche nel dispositivo. Windows App SDK fornisce la classe FileSavePicker per creare un'interfaccia coerente e intuitiva che consente agli utenti di scegliere dove salvare i file e cosa denominarli.

Questo articolo illustra come implementare una selezione salvataggio file nell'app WinUI. Imparerai come configurare l'aspetto e il comportamento del selettore, gestire la scelta dell'utente e salvare il contenuto nella posizione scelta.

La selezione file di salvataggio può essere popolata con un nome file suggerito e altre impostazioni predefinite per semplificare il salvataggio dei file da parte degli utenti:

Prerequisiti

Prima di iniziare, assicurarsi di avere:

• Un progetto WinUI configurato con Windows App SDK
• Conoscenza di base di C# e XAML
• Comprendere i modelli async/await in C#

API importanti

In questo argomento vengono usate le API seguenti:

• FileSavePicker
• StorageFile

Usa FileSavePicker per consentire agli utenti di specificare il nome e il percorso in cui vuoi che l'app salvi un file.

Salvare un documento con FileSavePicker

Usa un FileSavePicker per consentire agli utenti di specificare il nome, il tipo e il percorso di un file da salvare. Creare, personalizzare e visualizzare un oggetto selezione file e quindi salvare i dati tramite l'oggetto StorageFile restituito che rappresenta il file selezionato.

1. Creare e personalizzare FileSavePicker. Per iniziare, creare un nuovo oggetto FileSavePicker e quindi impostare le proprietà sull'oggetto per personalizzare la selezione file per l'app e gli utenti:

   using Microsoft.Windows.Storage.Pickers;
   ...
   var savePicker = new FileSavePicker(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 default file name. If not specified, use system default.
       SuggestedFileName = "My Document",
   
       // (Optional) Sets the folder that the file save dialog displays when it opens.
       //     If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
       SuggestedFolder = @"C:\MyFiles",
   
       // (Optional) specify the text displayed on the commit button. 
       //     If not specified, the system uses a default label of "Save" (suitably translated).
       CommitButtonText = "Save Document",
   
       // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
       //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
       FileTypeChoices = {
           { "Documents", new List<string> { ".txt", ".doc", ".docx" } }
       },
   
       // (Optional) specify the default file extension (will be appended to SuggestedFileName).
       //      If not specified, no extension will be appended.
       DefaultFileExtension = ".txt",
   };
   

   In questo esempio vengono impostate sei proprietà: SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices e DefaultFileExtension.

   Poiché l'utente salva un documento o un file di testo, l'esempio imposta SuggestedStartLocation sulla cartella della raccolta documenti usando il valore DocumentsLibrary dell'Enumerazione PickerLocationId . Impostare SuggestedStartLocation su un percorso appropriato per il tipo di file salvato, ad esempio Musica, Immagini, Video o Documenti. Dal percorso iniziale, l'utente può passare a e selezionare altre posizioni.

   Per evitare all'utente di digitare troppo, nell'esempio viene impostato SuggestedFileName. Il nome file suggerito deve essere rilevante per il file in fase di salvataggio. Ad esempio, come Word, è possibile suggerire il nome di file esistente se presente o la prima riga di un documento se l'utente salva un file che non ha ancora un nome.

   Utilizzare la proprietà FileTypeChoices quando si specificano i tipi di file supportati dall'esempio (documenti e file di testo di Microsoft Word). In questo modo l'app può aprire il file dopo il salvataggio. Assicurarsi che tutti i tipi di file specificati siano supportati dall'app. Gli utenti potranno salvare il file come qualsiasi tipo di file specificato. Possono anche modificare il tipo di file selezionando un altro dei tipi di file specificati. La prima scelta del tipo di file nell'elenco verrà selezionata per impostazione predefinita. Per controllarlo, impostare la proprietà DefaultFileExtension .

   Annotazioni

    La selezione file usa anche il tipo di file attualmente selezionato per filtrare i file visualizzati, in modo che all'utente vengano visualizzati solo i tipi di file corrispondenti ai tipi di file selezionati.

   Il codice C++ equivalente per questo esempio è il seguente:

   #include <winrt/Microsoft.Windows.Storage.Pickers.h>
   using namespace winrt::Microsoft::Windows::Storage::Pickers;
   
   FileSavePicker savePicker(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.
   savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
   
   // (Optional) specify the default file name. If not specified, use system default.
   savePicker.SuggestedFileName(L"NewDocument");
   
   // (Optional) Sets the folder that the file save dialog displays when it opens.
   //     If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
   savePicker.SuggestedFolder = L"C:\\MyFiles",
   
   // (Optional) specify the text displayed on the commit button. 
   //     If not specified, the system uses a default label of "Save" (suitably translated).
   savePicker.CommitButtonText(L"Save Document");
   
   // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
   //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
   savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
   
   // (Optional) specify the default file extension (will be appended to SuggestedFileName).
   //      If not specified, no extension will be appended.
   savePicker.DefaultFileExtension(L".txt");
   

   Annotazioni

     Gli oggetti FileSavePicker visualizzano la selezione file usando la modalità di visualizzazione PickerViewMode.List .

2. Successivamente, verrà mostrato il FileSavePicker e si procederà a salvare nel percorso del file scelto. Visualizzare il selettore di file chiamando PickSaveFileAsync. Dopo che l'utente specifica il nome, il tipo di file e il percorso e conferma di salvare il file, PickSaveFileAsync restituisce un oggetto FilePickResult leggero che contiene il percorso del file salvato e il nome file. È possibile acquisire ed elaborare questo file se si dispone dell'accesso in lettura e scrittura.

   using Microsoft.Windows.Storage.Pickers;
   ...
   var savePicker = new FileSavePicker(this.AppWindow.Id);
   var result = await savePicker.PickSaveFileAsync();
   if (result != null)
   {
       if (!System.IO.File.Exists(result.Path))
       {
           // Create a file and write to it.
           System.IO.File.WriteAllText(result.Path, "Hello world." + Environment.NewLine);
       }
       else
       {
           // Append to the existing file.
           System.IO.File.AppendAllText(result.Path, "Hello again." + Environment.NewLine);
       }
   }
   else
   {
       this.textBlock.Text = "Operation cancelled.";
   }
   

   L'esempio controlla se il file esiste e crea un nuovo file o aggiunge al file esistente. Se l'utente annulla l'operazione, il risultato sarà nulle sarà possibile gestire tale caso in modo appropriato, ad esempio la visualizzazione di un messaggio all'utente.

   Suggerimento

    È consigliabile controllare sempre il file salvato per assicurarsi che esista ed è valido prima di eseguire qualsiasi altra elaborazione. È quindi possibile salvare il contenuto nel file in base alle esigenze dell'app. L'app deve fornire un comportamento appropriato se il file selezionato non è valido.

   Di seguito è riportato l'equivalente C++ di questo esempio C#:

   #include <winrt/Microsoft.Windows.Storage.Pickers.h>
   #include <fstream>
   #include <string>
   using namespace winrt::Microsoft::Windows::Storage::Pickers;
   
   FileSavePicker savePicker(AppWindow().Id());
   auto result{ co_await savePicker.PickSaveFileAsync() };
   if (result)
   {
       // Check if the file exists.
       if (!std::ifstream(result.Path().c_str()))
       {
           std::ofstream outFile(result.Path().c_str());
           outFile << "Hello world.";
           outFile.close();
       }
       else
       {
           // Append to the existing file.
           std::ofstream outFile(result.Path().c_str(), std::ios::app);
           outFile << "Hello again.";
           outFile.close();
       }
   }
   else
   {
       textBlock().Text(L"Operation cancelled.");
   }
   

Contenuti correlati

Windows.Storage.Pickers

File, cartelle e librerie con Windows App SDK

PickSaveFileAsync