Zapisywanie pliku za pomocą selektora zestawu SDK aplikacji systemu Windows w usłudze WinUI

Podczas kompilowania aplikacji systemu Windows przy użyciu zestawu SDK aplikacji systemu Windows użytkownicy często muszą zapisywać pliki, takie jak dokumenty, obrazy lub inną zawartość do określonych lokalizacji na urządzeniu. Zestaw SDK aplikacji systemu Windows udostępnia klasę FileSavePicker w celu utworzenia spójnego, przyjaznego dla użytkownika interfejsu, który umożliwia użytkownikom wybór miejsca zapisywania plików i nazw.

W tym artykule pokazano, jak zaimplementować selektor zapisywania plików w aplikacji WinUI. Dowiesz się, jak skonfigurować wygląd i zachowanie selektora, obsługiwać wybór użytkownika i zapisywać zawartość w wybranej lokalizacji.

Selektor plików zapisywania można wypełnić sugerowaną nazwą pliku i innymi ustawieniami domyślnymi, aby ułatwić użytkownikom zapisywanie plików:

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

• Projekt WinUI skonfigurowany za pomocą zestawu SDK aplikacji systemu Windows
• Podstawowa znajomość języków C# i XAML
• Opis wzorców asynchronicznych/await w języku C#

Ważne interfejsy API

W tym temacie są używane następujące interfejsy API:

• FileSavePicker
• StorageFile

Użyj narzędzia FileSavePicker , aby umożliwić użytkownikom określenie nazwy i lokalizacji, w której aplikacja ma zapisać plik.

Zapisywanie dokumentu za pomocą narzędzia FileSavePicker

Użyj narzędzia FileSavePicker , aby użytkownicy mogli określić nazwę, typ i lokalizację pliku do zapisania. Utwórz, dostosuj i pokaż obiekt selektora plików, a następnie zapisz dane za pośrednictwem zwróconego obiektu StorageFile , który reprezentuje wybrany plik.

1. Utwórz i dostosuj platformę FileSavePicker. Zacznij od utworzenia nowego obiektu FileSavePicker , a następnie ustaw właściwości obiektu w celu dostosowania selektora plików dla aplikacji i użytkowników:

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

   W tym przykładzie ustawiono sześć właściwości: SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices i DefaultFileExtension.

   Ponieważ użytkownik zapisuje dokument lub plik tekstowy, przykład korzysta z wartości DocumentsLibrary z enumeracji PickerLocationId, aby ustawić właściwość SuggestedStartLocation na folder biblioteki dokumentów. Ustaw właściwość SuggestedStartLocation na lokalizację odpowiednią dla typu zapisywanego pliku, na przykład Muzyka, Obrazy, Filmy lub Dokumenty. Z miejsca startowego użytkownik może nawigować do innych lokalizacji i je wybrać.

   Aby oszczędzić użytkownikowi pisania, przykład ustawia SuggestedFileName. Sugerowana nazwa pliku powinna być odpowiednia dla zapisywanego pliku. Na przykład, podobnie jak program Word, możesz zasugerować istniejącą nazwę pliku, jeśli istnieje, lub pierwszy wiersz dokumentu, jeśli użytkownik zapisuje plik, który jeszcze nie ma nazwy.

   Użyj właściwości FileTypeChoices podczas specyfikacji typów plików, które obsługuje przykład (dokumenty programu Microsoft Word i pliki tekstowe). Dzięki temu aplikacja może otworzyć plik po jego zapisaniu. Upewnij się, że wszystkie określone typy plików są obsługiwane przez aplikację. Użytkownicy będą mogli zapisywać swój plik jako dowolny z określonych typów plików. Mogą również zmienić typ pliku, wybierając inny określony typ pliku. Wybór pierwszego typu pliku na liście zostanie domyślnie wybrany. Aby to kontrolować, ustaw właściwość DefaultFileExtension .

   Uwaga / Notatka

    Selektor plików używa również aktualnie wybranego typu pliku do filtrowania wyświetlanych plików, dzięki czemu tylko typy plików pasujące do wybranych typów plików są wyświetlane użytkownikowi.

   Odpowiedni kod języka C++ dla tego przykładu jest następujący:

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

   Uwaga / Notatka

     Obiekty FileSavePicker wyświetlają selektor plików przy użyciu trybu widoku PickerViewMode.List .

2. Następnie pokażmy okno FileSavePicker i zapiszmy w wybranej lokalizacji pliku. Wyświetl selektor plików, wywołując polecenie PickSaveFileAsync. Gdy użytkownik określi nazwę, typ pliku i lokalizację oraz potwierdzi zapisanie pliku, funkcja PickSaveFileAsync zwraca uproszczony obiekt FilePickResult zawierający ścieżkę do zapisanego pliku i nazwy pliku. Możesz przechwycić i przetworzyć ten plik, jeśli masz do niego dostęp do odczytu i zapisu.

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

   Przykład sprawdza, czy plik istnieje, i tworzy nowy plik lub dołącza do istniejącego pliku. Jeśli użytkownik anuluje operację, wynikiem będzie null, i możesz odpowiednio obsłużyć ten przypadek, na przykład wyświetlenie komunikatu dla użytkownika.

   Wskazówka

    Zawsze należy sprawdzić zapisany plik, aby upewnić się, że istnieje i jest prawidłowy przed wykonaniem jakiegokolwiek innego przetwarzania. Następnie możesz zapisać zawartość w pliku zgodnie z potrzebami aplikacji. Aplikacja powinna zapewnić odpowiednie zachowanie, jeśli wybrany plik nie jest prawidłowy.

   Oto odpowiednik w C++ dla tego przykładu w 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.");
   }
   

Treści powiązane

Windows.Storage.Pickers

Pliki, foldery i biblioteki z zestawem SDK aplikacji systemu Windows

PickSaveFileAsync