FileSavePicker Kelas

Definisi

Ruang nama:

Windows.Storage.Pickers

Mewakili pemilih file yang memungkinkan pengguna memilih nama file, ekstensi, dan lokasi penyimpanan untuk file.

Di aplikasi desktop, sebelum menggunakan instans kelas ini dengan cara yang menampilkan UI, Anda harus mengaitkan objek dengan handel jendela pemiliknya. Untuk informasi selengkapnya, dan contoh kode, lihat Menampilkan objek UI WinRT yang bergantung pada CoreWindow.

public ref class FileSavePicker sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class FileSavePicker final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class FileSavePicker

function FileSavePicker()

Public NotInheritable Class FileSavePicker

Warisan

Object Platform::Object IInspectable FileSavePicker

Atribut

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Persyaratan Windows

Rangkaian perangkat	Windows 10 (diperkenalkan dalam 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (diperkenalkan dalam v1.0)

Contoh

Sampel Pemilih file tersedia dalam versi C# dan C++/WinRT. Ini menunjukkan cara memeriksa apakah aplikasi di-snap, cara mengatur properti pemilih file, dan cara menampilkan pemilih file sehingga pengguna dapat menyimpan file.

Berikut adalah kutipan dari versi C# dari aplikasi sampel.

if (rootPage.EnsureUnsnapped())
{
    FileSavePicker savePicker = new FileSavePicker();
    savePicker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
    // Dropdown of file types the user can save the file as
    savePicker.FileTypeChoices.Add("Plain Text", new List<string>() { ".txt" });
    // Default file name if the user does not type one in or select a file to replace
    savePicker.SuggestedFileName = "New Document";

    StorageFile file = await savePicker.PickSaveFileAsync();
    if (file != null)
    {
        // Prevent updates to the remote version of the file until we finish making changes and call CompleteUpdatesAsync.
        CachedFileManager.DeferUpdates(file);
        // write to file
        await FileIO.WriteTextAsync(file, file.Name);
        // Let Windows know that we're finished changing the file so the other app can update the remote version of the file.
        // Completing updates may require Windows to ask for user input.
        FileUpdateStatus status = await CachedFileManager.CompleteUpdatesAsync(file);
        if (status == FileUpdateStatus.Complete)
        {
            OutputTextBlock.Text = "File " + file.Name + " was saved.";
        }
        else
        {
            OutputTextBlock.Text = "File " + file.Name + " couldn't be saved.";
        }
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
}

Keterangan

Penting

Anda harus menggunakan properti properti FileTypeChoices untuk menentukan satu atau beberapa jenis file sebelum Anda memanggil metode PickSaveFileAsync, atau pemilih akan memberikan pengecualian.

Untuk mempelajari cara menyimpan file melalui pemilih file, lihat Cara menyimpan file melalui pemilih file.

Untuk mulai mengakses pemilih file dan folder, lihat File, folder, dan pustaka .

Peringatan

Jika Anda mencoba menampilkan pemilih file saat aplikasi Anda diposisikan, pemilih file tidak akan ditampilkan dan pengecualian akan dilemparkan. Anda dapat menghindari hal ini dengan memastikan aplikasi Anda tidak diposisikan atau dengan membatalkan pemilih file sebelum Memanggil pemilih file. Contoh kode berikut dan sampel Pemilih file menunjukkan caranya.

Di aplikasi desktop yang memerlukan elevasi

Di aplikasi desktop (yang mencakup aplikasi WinUI 3), Anda dapat menggunakan FileSavePicker (dan jenis lain dari Windows.Storage.Pickers). Tetapi jika aplikasi desktop memerlukan elevasi untuk berjalan, maka Anda memerlukan pendekatan yang berbeda (itu karena API ini tidak dirancang untuk digunakan dalam aplikasi yang ditinggikan). Cuplikan kode di bawah ini menggambarkan bagaimana Anda dapat menggunakan C#/Win32 P/Invoke Source Generator (CsWin32) untuk memanggil API pemilihan Win32 sebagai gantinya. Untuk mempelajari cara menggunakan CsWin32, ikuti tautan tersebut untuk dokumentasi.

// NativeMethods.txt
CoCreateInstance
FileSaveDialog
IFileSaveDialog
SHCreateItemFromParsingName

// MainWindow.xaml
...
<TextBlock x:Name="OutputTextBlock"/>
...

// MainWindow.xaml.cs
using Microsoft.UI.Xaml;
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;

using Windows.Win32;
using Windows.Win32.Foundation;
using Windows.Win32.System.Com;
using Windows.Win32.UI.Shell;
using Windows.Win32.UI.Shell.Common;

namespace FileSavePickerExample
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
        }

        private unsafe void myButton_Click(object sender, RoutedEventArgs e)
        {
            try
            {
                // Retrieve the window handle (HWND) of the main WinUI 3 window.
                var hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);

                int hr = PInvoke.CoCreateInstance<IFileSaveDialog>(
                    typeof(FileSaveDialog).GUID,
                    null,
                    CLSCTX.CLSCTX_INPROC_SERVER,
                    out var fsd);
                if (hr < 0)
                {
                    Marshal.ThrowExceptionForHR(hr);
                }

                // Set file type filters.
                string filter = "Word Documents|*.docx|JPEG Files|*.jpg";

                List<COMDLG_FILTERSPEC> extensions = new List<COMDLG_FILTERSPEC>();

                if (!string.IsNullOrEmpty(filter))
                {
                    string[] tokens = filter.Split('|');
                    if (0 == tokens.Length % 2)
                    {
                        // All even numbered tokens should be labels.
                        // Odd numbered tokens are the associated extensions.
                        for (int i = 1; i < tokens.Length; i += 2)
                        {
                            COMDLG_FILTERSPEC extension;

                            extension.pszSpec = (char*)Marshal.StringToHGlobalUni(tokens[i]);
                            extension.pszName = (char*)Marshal.StringToHGlobalUni(tokens[i - 1]);
                            extensions.Add(extension);
                        }
                    }
                }

                fsd.SetFileTypes(extensions.ToArray());

                // Set the default folder.
                hr = PInvoke.SHCreateItemFromParsingName(
                    Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
                    null,
                    typeof(IShellItem).GUID,
                    out var directoryShellItem);
                if (hr < 0)
                {
                    Marshal.ThrowExceptionForHR(hr);
                }

                fsd.SetFolder((IShellItem)directoryShellItem);
                fsd.SetDefaultFolder((IShellItem)directoryShellItem);

                // Set the default file name.
                fsd.SetFileName($"{DateTime.Now:yyyyMMddHHmm}");

                // Set the default extension.
                fsd.SetDefaultExtension(".docx");

                fsd.Show(new HWND(hWnd));

                fsd.GetResult(out var ppsi);

                PWSTR filename;
                ppsi.GetDisplayName(SIGDN.SIGDN_FILESYSPATH, &filename);

                OutputTextBlock.Text = filename.ToString();
            }
            catch (Exception ex)
            {
                OutputTextBlock.Text = "a problem occured: " + ex.Message;
            }
        }
    }
}

Riwayat versi

Versi Windows	Versi SDK	Nilai ditambahkan
1903	18362	CreateForUser
1903	18362	Pengguna

Konstruktor

FileSavePicker()

Membuat instans baru FileSavePicker. Di aplikasi desktop, sebelum menggunakan instans kelas ini dengan cara yang menampilkan UI, Anda harus mengaitkan objek dengan handel jendela pemiliknya. Untuk informasi selengkapnya, dan contoh kode, lihat Menampilkan objek UI WinRT yang bergantung pada CoreWindow.

Properti

CommitButtonText	Mendapatkan atau mengatur teks label tombol penerapan di UI pemilih file.
ContinuationData	Mendapatkan serangkaian nilai yang akan diisi oleh aplikasi sebelum operasi PickSaveFileAndContinue yang menonaktifkan aplikasi untuk memberikan konteks saat aplikasi diaktifkan. (aplikasi Windows Phone 8.x)
DefaultFileExtension	Penting Jangan gunakan properti ini. Gunakan properti FileTypeChoices sebagai gantinya. Ekstensi file default diatur oleh jenis file pertama dalam grup jenis file pertama di FileTypeChoices. Mendapatkan atau mengatur ekstensi nama file default yang diberikan fileSavePicker ke file yang akan disimpan.
EnterpriseId	Mendapatkan atau mengatur ID yang menentukan perusahaan yang memiliki file.
FileTypeChoices	Mendapatkan kumpulan jenis file valid yang dapat dipilih pengguna untuk ditetapkan ke file.
SettingsIdentifier	Mendapatkan atau mengatur pengidentifikasi pengaturan yang terkait dengan instans FileSavePicker saat ini.
SuggestedFileName	Mendapatkan atau mengatur nama file yang disarankan pemilih penyimpanan file kepada pengguna.
SuggestedSaveFile	Mendapatkan atau mengatur storageFile yang disarankan pemilih file kepada pengguna untuk menyimpan file.
SuggestedStartLocation	Mendapatkan atau mengatur lokasi yang disarankan pemilih penyimpanan file kepada pengguna sebagai lokasi untuk menyimpan file.
User	Mendapatkan info tentang pengguna tempat FileSavePicker dibuat. Gunakan properti ini untuk aplikasi multi-pengguna.

Metode

CreateForUser(User)	Membuat FileSavePicker yang dilingkup ke direktori pribadi pengguna yang ditentukan. Gunakan metode ini untuk aplikasi multi-pengguna.
PickSaveFileAndContinue()	Usang pada Windows 10; gunakan PickSaveFileAsync sebagai gantinya. Menampilkan pemilih file sehingga pengguna dapat menyimpan file, menonaktifkan dan aplikasi serta mengaktifkannya kembali saat operasi selesai. (aplikasi Windows Phone 8.x)
PickSaveFileAsync()	Memperlihatkan pemilih file sehingga pengguna dapat menyimpan file dan mengatur nama file, ekstensi, dan lokasi file yang akan disimpan. (Aplikasi UWP)

Lihat juga

• StorageFile
• Sampel pemilih file (Windows 10)
• File, folder, dan pustaka
• Cara menyimpan file dengan pemilih file
• Menampilkan objek UI WinRT yang bergantung pada CoreWindow