Uložení souboru ve WinUI pomocí výběru Windows App SDK

Při vytváření aplikací pro Windows pomocí sady Windows App SDK uživatelé často potřebují ukládat soubory, jako jsou dokumenty, obrázky nebo jiný obsah, do konkrétních umístění na svém zařízení. Sada Windows App SDK poskytuje třídu FileSavePicker pro vytvoření konzistentního a uživatelsky přívětivého rozhraní, které umožňuje uživatelům zvolit, kam se mají ukládat soubory a jak je pojmenovat.

V tomto článku se dozvíte, jak implementovat výběr ukládání souborů v aplikaci WinUI. Dozvíte se, jak nakonfigurovat vzhled a chování výběru, zpracovat výběr uživatele a uložit obsah do zvoleného umístění.

Výběr souboru pro ukládání se dá naplnit navrhovaným názvem souboru a dalším výchozím nastavením, aby uživatelé mohli snadněji ukládat soubory:

Požadavky

Než začnete, ujistěte se, že máte:

• Projekt WinUI nastavený pomocí sady Windows App SDK
• Základní znalost jazyka C# a XAML
• Pochopení asynchronních vzorů pomocí klíčových slov async/await v jazyce C#

Důležitá rozhraní API

V tomto tématu se používají následující rozhraní API:

• FileSavePicker
• StorageFile

Pomocí FileSavePickeru můžete uživatelům povolit, aby zadali název a umístění, kam má vaše aplikace uložit soubor.

Uložení dokumentu pomocí FileSavePickeru

Použijte FileSavePicker , aby uživatelé mohli zadat název, typ a umístění souboru, který chcete uložit. Vytvořte, přizpůsobte a zobrazte objekt pro výběr souboru a potom uložte data prostřednictvím vráceného objektu StorageFile , který představuje vybraný soubor.

1. Vytvořte a přizpůsobte FileSavePicker. Začněte vytvořením nového objektu FileSavePicker a nastavením vlastností objektu upravte výběr souborů pro vaši aplikaci a uživatele:

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

   Tento příklad nastaví šest vlastností: SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices a DefaultFileExtension.

   Vzhledem k tomu, že uživatel ukládá dokument nebo textový soubor, ukázka nastaví SuggestedStartLocation do složky knihovny dokumentů pomocí hodnoty DocumentsLibrary z výčtu PickerLocationId . Nastavte SuggestedStartLocation na umístění, které je vhodné pro typ uloženého souboru, například Hudba, Obrázky, Videa nebo Dokumenty. Z počátečního místa může uživatel přejít na jiné lokace a vybrat je.

   Aby uživatel nemusel tolik psát, příklad nastaví SuggestedFileName. Navrhovaný název souboru by měl být relevantní pro soubor, který se ukládá. Například Word můžete navrhnout název existujícího souboru, pokud existuje, nebo první řádek dokumentu, pokud uživatel ukládá soubor, který ještě nemá název.

   Vlastnost FileTypeChoices použijte při specifikaci typů souborů, které ukázka podporuje (dokumenty Aplikace Microsoft Word a textové soubory). Tím zajistíte, že aplikace bude moct soubor po uložení otevřít. Ujistěte se, že vaše aplikace podporuje všechny typy souborů, které zadáte. Uživatelé budou moct soubor uložit jako kterýkoli ze zadaných typů souborů. Můžou také změnit typ souboru výběrem jiného ze zadaných typů souborů. Ve výchozím nastavení bude vybrána první volba typu souboru v seznamu. Chcete-li řídit, nastavte DefaultFileExtension vlastnost.

   Poznámka:

    Výběr souboru také používá aktuálně vybraný typ souboru k filtrování zobrazených souborů, aby se uživateli zobrazily pouze typy souborů, které odpovídají vybraným typům souborů.

   Ekvivalentní kód jazyka C++ pro tento příklad je následující:

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

   Poznámka:

     Objekty FileSavePicker zobrazují výběr souboru pomocí režimu zobrazení PickerViewMode.List .

2. Dále si ukážeme FileSavePicker a uložíme ho do vybraného umístění souboru. Zobrazte výběr souboru pomocí volání PickSaveFileAsync. Jakmile uživatel zadá název, typ souboru a umístění a potvrdí uložení souboru, vrátí PickSaveFileAsync jednoduchý filePickResult objekt, který obsahuje cestu k uloženému souboru a souboru. Tento soubor můžete zachytit a zpracovat, pokud k němu máte přístup pro čtení a zápis.

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

   Příklad zkontroluje, jestli soubor existuje, a buď vytvoří nový soubor, nebo připojí k existujícímu souboru. Pokud uživatel operaci zruší, výsledek bude nulla můžete tento případ zpracovat odpovídajícím způsobem, například zobrazení zprávy uživateli.

   Návod

    Před provedením jakéhokoli jiného zpracování byste měli vždy zkontrolovat uložený soubor a ujistit se, že existuje a je platný. Potom můžete obsah uložit do souboru podle potřeby pro vaši aplikaci. Pokud vybraný soubor není platný, měla by vaše aplikace poskytovat odpovídající chování.

   Tady je ekvivalent jazyka C++ tohoto příkladu jazyka 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.");
   }
   

Související obsah

Windows.Storage.Pickers

Soubory, složky a knihovny pomocí sady Windows App SDK

PickSaveFileAsync