FileSavePicker 类

定义

命名空间:

Windows.Storage.Pickers

表示一个文件选取器，它允许用户选择文件的文件名、扩展名和存储位置。

在桌面应用中，在以显示 UI 的方式使用此类实例之前，需要将 对象与其所有者的窗口句柄相关联。 有关详细信息和代码示例，请参阅 显示依赖于 CoreWindow 的 WinRT UI 对象。

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

继承

Object Platform::Object IInspectable FileSavePicker

属性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 要求

设备系列	Windows 10 (在 10.0.10240.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v1.0 中引入)

示例

文件选取器示例在 C# 和 C++/WinRT 版本中可用。 它演示如何检查应用是否贴靠、如何设置文件选取器属性以及如何显示文件选取器以便用户可以保存文件。

下面是示例应用的 C# 版本的摘录。

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

注解

重要

在调用 PickSaveFileAsync 方法之前，必须使用 FileTypeChoices 属性 指定一个或多个文件类型，否则选取器将引发异常。

若要了解如何通过文件选取器保存文件，请参阅 如何通过文件选取器保存文件。

若要开始访问文件和文件夹文件选取器，请参阅 文件、文件夹和库 。

警告

如果在贴靠应用时尝试显示文件选取器，则不会显示文件选取器，并且会引发异常。 可以通过确保应用未贴靠或在调用文件选取器之前取消应用来避免此问题。 以下代码示例和 文件选取器示例 演示了操作方法。

在需要提升权限的桌面应用中

在桌面应用 (（包括 WinUI 3 应用) ）中，可以使用 Windows.Storage.Pickers) 中的 FileSavePicker (和其他类型。 但是，如果桌面应用需要提升才能运行，则需要使用不同的方法 (这是因为这些 API 不是设计用于提升的应用) 。 以下代码片段演示了如何使用 C#/Win32 P/Invoke 源生成器 (CsWin32) 来调用 Win32 选取 API。 若要了解如何使用 CsWin32，请单击文档链接。

// 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;
            }
        }
    }
}

版本历史记录

Windows 版本	SDK 版本	增值
1903	18362	CreateForUser
1903	18362	用户

构造函数

FileSavePicker()

创建 FileSavePicker 的新实例。 在桌面应用中，在以显示 UI 的方式使用此类实例之前，需要将 对象与其所有者的窗口句柄相关联。 有关详细信息和代码示例，请参阅 显示依赖于 CoreWindow 的 WinRT UI 对象。

属性

CommitButtonText	获取或设置文件选取器 UI 中提交按钮的标签文本。
ContinuationData	获取应用在 PickSaveFileAndContinue 操作之前要填充的一组值，该操作停用应用，以便在激活应用时提供上下文。 (Windows Phone 8.x 应用)
DefaultFileExtension	重要 请勿使用此属性。 请改用 FileTypeChoices 属性 。 默认文件扩展名由 FileTypeChoices 中第一个文件类型组中的第一个文件类型设置。 获取或设置 fileSavePicker 提供给要保存的文件的默认文件扩展名。
EnterpriseId	获取或设置一个 ID，该 ID 指定拥有该文件的企业。
FileTypeChoices	获取用户可以选择分配给文件的有效文件类型的集合。
SettingsIdentifier	获取或设置与当前 FileSavePicker 实例关联的设置标识符。
SuggestedFileName	获取或设置文件保存选取器向用户建议的文件名。
SuggestedSaveFile	获取或设置文件选取器建议用户保存文件的 storageFile 。
SuggestedStartLocation	获取或设置文件保存选取器向用户建议的位置作为保存文件的位置。
User	获取有关为其创建了 FileSavePicker 的用户的信息。 将此属性用于 多用户应用程序。

方法

CreateForUser(User)	创建范围限定为指定用户的个人目录的 FileSavePicker 。 将此方法用于 多用户应用程序。
PickSaveFileAndContinue()	自 Windows 10 起已过时;请改用 PickSaveFileAsync。 显示文件选取器，以便用户可以保存文件、停用和应用，并在操作完成后重新激活它。 (Windows Phone 8.x 应用)
PickSaveFileAsync()	显示文件选取器，以便用户可以保存文件并设置要保存的文件的文件名、扩展名和位置。 (UWP 应用)

另请参阅

• StorageFile
• 文件选取器示例 (Windows 10)
• 文件、文件夹和库
• 如何使用文件选取器保存文件
• 显示依赖于 CoreWindow 的 WinRT UI 对象