Tutorial: Menyimpan file dengan pemilih aplikasi SDK Aplikasi Windows di WinUI

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

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:

• SDK Aplikasi Windows 1.8 atau yang lebih baru. Microsoft.Windows.Storage.Pickers API yang digunakan dalam artikel ini diperkenalkan di SDK Aplikasi Windows 1.8. Jika proyek Anda ditujukan untuk versi sebelumnya, lihat Menggunakan pemilih WinRT dengan interop HWND untuk pendekatan lama.
• Proyek WinUI disiapkan dengan SDK Aplikasi Windows
• Pemahaman dasar tentang C# dan XAML
• Pemahaman tentang pola asinkron/tunggu di C#

API penting

API berikut digunakan dalam topik ini:

• FileSavePicker
• PickFileResult

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 dengan menggunakan PickFileResult yang dikembalikan, yang berisi jalur file yang dipilih. Jika Anda memerlukan nama file, dapatkan dari jalur tersebut.

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

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

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 dapat menyarankan nama file yang 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 (Microsoft Word dokumen 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.

Nota

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

2. Selanjutnya, 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 PickFileResult ringan yang berisi jalur ke file yang disimpan. Jika Anda memerlukan nama file, dapatkan dari jalur tersebut. 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.";
    }

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

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.

Konten terkait

• namespace Microsoft.Windows.Storage.Pickers
• Membuka file dan folder dengan pemilih SDK Aplikasi Windows
• File, folder, dan pustaka dengan SDK Aplikasi Windows
• Mengambil sebuah handle jendela (HWND)
• Panggil API interop dari aplikasi .NET
• Menampilkan objek UI WinRT yang bergantung pada CoreWindow
• Contoh pemilih file di Galeri WinUI