Enregistrer un fichier avec le sélecteur de SDK d’application Windows dans WinUI

Lors de la création d’applications Windows avec le Kit de développement logiciel (SDK) d’application Windows, les utilisateurs doivent souvent enregistrer des fichiers tels que des documents, des images ou d’autres contenus à des emplacements spécifiques sur leur appareil. Le Kit de développement logiciel (SDK) d’application Windows fournit la classe FileSavePicker pour créer une interface cohérente et conviviale qui permet aux utilisateurs d’enregistrer des fichiers et de les nommer.

Cet article explique comment implémenter un sélecteur d’enregistrement de fichiers dans votre application WinUI. Vous allez apprendre à configurer l’apparence et le comportement du sélecteur, à gérer la sélection de l’utilisateur et à enregistrer du contenu à l’emplacement choisi.

Le sélecteur de fichiers d’enregistrement peut être rempli avec un nom de fichier suggéré et d’autres paramètres par défaut pour faciliter l’enregistrement de leurs fichiers par les utilisateurs :

Prerequisites

Avant de commencer, vérifiez que vous disposez des points suivants :

• Un projet WinUI configuré avec le Kit de développement logiciel (SDK) d’application Windows
• Connaissance de base de C# et XAML
• Compréhension des modèles asynchrones/await en C#

API importantes

Les API suivantes sont utilisées dans cette rubrique :

• FileSavePicker
• StorageFile

Utilisez FileSavePicker pour permettre aux utilisateurs de spécifier le nom et l’emplacement où ils souhaitent que votre application enregistre un fichier.

Enregistrer un document avec FileSavePicker

Utilisez un FileSavePicker pour que vos utilisateurs puissent spécifier le nom, le type et l’emplacement d’un fichier à enregistrer. Créez, personnalisez et affichez un objet sélecteur de fichiers, puis enregistrez des données via l’objet StorageFile retourné qui représente le fichier sélectionné.

1. Créez et personnalisez FileSavePicker. Commencez par créer un objet FileSavePicker , puis définissez des propriétés sur l’objet pour personnaliser le sélecteur de fichiers pour votre application et vos utilisateurs :

   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",
   };
   

   Cet exemple montre comment définir six propriétés : SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices et DefaultFileExtension.

   Étant donné que l’utilisateur enregistre un document ou un fichier texte, l’exemple définit SuggestedStartLocation sur le dossier de bibliothèque de documents à l’aide de la valeur DocumentsLibrary de l’énumération PickerLocationId . Définissez SuggestedStartLocation sur un emplacement approprié pour le type de fichier enregistré, par exemple Musique, Images, Vidéos ou Documents. À partir de l’emplacement de début, l’utilisateur peut accéder à d’autres emplacements et sélectionner d’autres emplacements.

   Pour épargner à l'utilisateur la saisie de texte, l'exemple définit un SuggestedFileName. Le nom de fichier suggéré doit être pertinent pour le fichier enregistré. Par exemple, comme Word, vous pouvez suggérer le nom de fichier existant s’il en existe un ou la première ligne d’un document si l’utilisateur enregistre un fichier qui n’a pas encore de nom.

   Utilisez la propriété FileTypeChoices lors de la spécification des types de fichiers pris en charge par l’exemple (documents Microsoft Word et fichiers texte). Cela garantit que l’application peut ouvrir le fichier après son enregistrement. Vérifiez que tous les types de fichiers que vous spécifiez sont pris en charge par votre application. Les utilisateurs pourront enregistrer leur fichier comme l’un des types de fichiers que vous spécifiez. Ils peuvent également modifier le type de fichier en sélectionnant un autre des types de fichiers que vous avez spécifiés. Le premier choix de type de fichier dans la liste est sélectionné par défaut. Pour contrôler cela, définissez la propriété DefaultFileExtension .

   Note

    Le sélecteur de fichiers utilise également le type de fichier actuellement sélectionné pour filtrer les fichiers qu’il affiche, afin que seuls les types de fichiers correspondant aux types de fichiers sélectionnés soient affichés à l’utilisateur.

   Le code C++ équivalent pour cet exemple est le suivant :

   #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");
   

   Note

     Les objets FileSavePicker affichent le sélecteur de fichiers à l’aide du mode d’affichage PickerViewMode.List .

2. Ensuite, nous allons afficher le FileSavePicker et enregistrer à l’emplacement du fichier sélectionné. Affichez le sélecteur de fichiers en appelant PickSaveFileAsync. Une fois que l’utilisateur spécifie le nom, le type de fichier et l’emplacement, et confirme l’enregistrement du fichier, PickSaveFileAsync retourne un objet FilePickResult léger qui contient le chemin d’accès au fichier enregistré et au nom de fichier. Vous pouvez capturer et traiter ce fichier si vous avez accès en lecture et en écriture à ce fichier.

   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’exemple vérifie si le fichier existe et crée un fichier ou ajoute au fichier existant. Si l’utilisateur annule l’opération, le résultat sera null, et vous pouvez gérer ce cas de manière appropriée, par exemple l’affichage d’un message à l’utilisateur.

   Conseil / Astuce

    Vous devez toujours vérifier le fichier enregistré pour vous assurer qu’il existe et qu’il est valide avant d’effectuer tout autre traitement. Ensuite, vous pouvez enregistrer du contenu dans le fichier selon les besoins de votre application. Votre application doit fournir un comportement approprié si le fichier sélectionné n’est pas valide.

   Voici l’équivalent C++ de cet exemple 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.");
   }
   

Contenu connexe

Windows.Storage.Pickers

Fichiers, dossiers et bibliothèques avec le Kit de développement logiciel (SDK) d’application Windows

PickSaveFileAsync