FileSavePicker Класс

Определение

Пространство имен:

Windows.Storage.Pickers

Представляет средство выбора файлов, которое позволяет пользователю выбрать имя файла, расширение и место хранения для файла.

В классическом приложении перед использованием экземпляра этого класса таким образом, который отображает пользовательский интерфейс, необходимо связать объект с дескриптором окна владельца. Дополнительные сведения и примеры кода см. в статье Отображение объектов пользовательского интерфейса WinRT, зависящих от 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

Наследование

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

Комментарии

Важно!

Необходимо использовать свойство FileTypeChoices , чтобы указать один или несколько типов файлов перед вызовом метода PickSaveFileAsync, иначе средство выбора создаст исключение.

Сведения о том, как сохранять файлы с помощью средства выбора файлов, см. в статье Сохранение файлов с помощью средства выбора файлов.

Чтобы приступить к доступу к выбору файлов и папок, см. статью Файлы, папки и библиотеки .

Предупреждение

Если вы попытаетесь отобразить средство выбора файлов во время привязки приложения, средство выбора файлов не будет отображаться и возникнет исключение. Этого можно избежать, убедившись, что приложение не прикреплено или отключив его перед вызовом средства выбора файлов. В следующих примерах кода и в примере средства выбора файлов показано, как это сделать.

В классическом приложении, требующего повышения прав

В классическом приложении (включая приложения WinUI 3) можно использовать FileSavePicker (и другие типы из Windows.Storage.Pickers). Но если классическому приложению требуется повышение прав, вам потребуется другой подход (это связано с тем, что эти API не предназначены для использования в приложении с повышенными привилегиями). В приведенном ниже фрагменте кода показано, как можно использовать генератор источника C#/Win32 P/Invoke (CsWin32) для вызова API-интерфейсов выбора Win32. Чтобы узнать, как использовать 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. В классическом приложении перед использованием экземпляра этого класса таким образом, который отображает пользовательский интерфейс, необходимо связать объект с дескриптором окна владельца. Дополнительные сведения и примеры кода см. в статье Отображение объектов пользовательского интерфейса WinRT, зависящих от CoreWindow.

Свойства

CommitButtonText	Возвращает или задает текст метки кнопки фиксации в пользовательском интерфейсе средства выбора файлов.
ContinuationData	Возвращает набор значений, заполняемых приложением перед операцией PickSaveFileAndContinue , которая отключает приложение для предоставления контекста при активации приложения. (приложение Windows Phone версии 8.x)
DefaultFileExtension	Важно! Не используйте это свойство. Вместо этого используйте свойство FileTypeChoices . Расширение файла по умолчанию задается по первому типу файла в первой группе типов файлов в FileTypeChoices. Возвращает или задает расширение имени файла по умолчанию, которое fileSavePicker присваивает файлам для сохранения.
EnterpriseId	Возвращает или задает идентификатор, указывающий предприятие, которому принадлежит файл.
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)
• Файлы, папки и библиотеки
• Сохранение файлов с помощью средства выбора файлов
• Отображение объектов пользовательского интерфейса WinRT, зависящих от CoreWindow