Simpan berkas menggunakan pemilih berkas Windows App SDK di WinUI

Saat membangun aplikasi Windows dengan Windows App SDK, pengguna sering kali perlu menyimpan file seperti dokumen, gambar, atau konten lainnya ke lokasi tertentu di perangkat mereka. Windows App SDK menyediakan kelas FileSavePicker untuk membuat antarmuka yang konsisten dan mudah digunakan yang memungkinkan pengguna memilih tempat menyimpan file dan apa yang harus dinamai.

Artikel ini memperlihatkan kepada Anda cara menerapkan pemilih penyimpanan file di aplikasi WinUI Anda. Anda akan mempelajari cara mengonfigurasi tampilan dan perilaku pemilih, menangani pilihan pengguna, dan menyimpan konten ke lokasi yang dipilih.

Pemilih file penyimpanan dapat diisi dengan nama file yang disarankan dan pengaturan default lainnya untuk memudahkan pengguna menyimpan file mereka:

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Proyek WinUI disiapkan dengan Windows App SDK
• Pemahaman dasar tentang C# dan XAML
• Pemahaman tentang pola asinkron/tunggu di C#

API penting

API berikut digunakan dalam topik ini:

• FileSavePicker
• StorageFile

Gunakan FileSavePicker untuk memungkinkan pengguna menentukan nama dan lokasi tempat mereka ingin aplikasi Anda menyimpan file.

Menyimpan dokumen dengan FileSavePicker

Gunakan FileSavePicker sehingga pengguna Anda dapat menentukan nama, jenis, dan lokasi file untuk disimpan. Buat, sesuaikan, dan tampilkan objek pemilih file, lalu simpan data melalui objek StorageFile yang dikembalikan yang mewakili file yang dipilih.

1. Buat dan sesuaikan FileSavePicker. Mulailah dengan membuat objek FileSavePicker baru, lalu atur properti pada objek untuk menyesuaikan pemilih file untuk aplikasi dan pengguna Anda:

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

   Contoh ini menetapkan enam properti: SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices, dan DefaultFileExtension.

   Karena pengguna menyimpan file dokumen atau teks, sampel mengatur SuggestedStartLocation ke folder pustaka dokumen dengan menggunakan nilai DocumentsLibrary dari Enum PickerLocationId . Atur SuggestedStartLocation ke lokasi yang sesuai untuk jenis file yang disimpan, misalnya Musik, Gambar, Video, atau Dokumen. Dari lokasi awal, pengguna dapat menavigasi ke dan memilih lokasi lain.

   Untuk menghemat beberapa pengetikan bagi pengguna, contoh menetapkan SuggestedFileName. Nama file yang disarankan harus relevan dengan file yang disimpan. Misalnya, seperti Word, Anda bisa menyarankan nama file yang sudah ada jika ada, atau baris pertama dokumen jika pengguna menyimpan file yang belum memiliki nama.

   Gunakan properti FileTypeChoices saat menspesifikasikan jenis file yang didukung sampel (dokumen Microsoft Word dan file teks). Ini memastikan bahwa aplikasi dapat membuka file setelah disimpan. Pastikan semua jenis file yang Anda tentukan didukung oleh aplikasi Anda. Pengguna akan dapat menyimpan file mereka sebagai salah satu jenis file yang Anda tentukan. Mereka juga dapat mengubah jenis file dengan memilih jenis file lain yang Anda tentukan. Pilihan tipe file pertama dalam daftar akan dipilih secara default. Untuk mengontrolnya, atur properti DefaultFileExtension .

   Nota

    Pemilih file juga menggunakan tipe file yang saat ini dipilih untuk memfilter file mana yang ditampilkannya, sehingga hanya tipe file yang cocok dengan tipe file yang dipilih yang ditampilkan kepada pengguna.

   Kode C++ yang setara untuk contoh ini adalah sebagai berikut:

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

   Nota

     Objek FileSavePicker menampilkan pemilih file menggunakan mode tampilan PickerViewMode.List .

2. Selanjutnya, mari kita tampilkan FileSavePicker dan simpan ke lokasi file yang dipilih. Tampilkan pemilih file dengan memanggil PickSaveFileAsync. Setelah pengguna menentukan nama, jenis file, dan lokasi, dan mengonfirmasi untuk menyimpan file, PickSaveFileAsync mengembalikan objek FilePickResult ringan yang berisi jalur ke file yang disimpan dan nama file. Anda dapat mengambil dan memproses file ini jika Anda telah membaca dan menulis akses ke file tersebut.

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

   Contoh memeriksa apakah file ada dan membuat file baru atau menambahkan ke file yang ada. Jika pengguna membatalkan operasi, hasilnya adalah null, dan Anda dapat menangani kasus tersebut dengan tepat, seperti menampilkan pesan kepada pengguna.

   Tip

    Anda harus selalu memeriksa file yang disimpan untuk memastikan file tersebut ada dan valid sebelum Anda melakukan pemrosesan lainnya. Kemudian, Anda dapat menyimpan konten ke file yang sesuai untuk aplikasi Anda. Aplikasi Anda harus memberikan perilaku yang sesuai jika file yang dipilih tidak valid.

   Berikut adalah C++ yang setara dengan contoh C# ini:

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

Konten terkait

Windows.Storage.Pickers

File, folder, dan pustaka dengan Windows App SDK

PickSaveFileAsync