Открытие файлов и папок с помощью средства выбора в WinUI

Используйте средства выбора файлов и папок пакета SDK для Windows, чтобы пользователи могут просматривать и выбирать файлы или папки в приложении WinUI. API выбора предоставляют знакомый интерфейс пользователя Windows, который помогает пользователям навигации по устройству и облачным хранилищам. В этой статье показано, как реализовать средства выбора файлов и средства выбора папок, настроить их поведение и обрабатывать выбранные результаты в приложении.

Классы FileOpenPicker и FileSavePicker для приложений Windows создают диалоговое окно выбора, позволяющее пользователям указать имя и расположение файла для открытия или сохранения. Класс FolderPicker позволяет выбрать папку.

Дополнительные сведения об использовании средства выбора для сохранения файлов см. в статье "Сохранение файла с помощью средства выбора пакета SDK для приложений Windows".

Важные API

В этой статье используются следующие API:

Пользовательский интерфейс средства выбора файлов

Средство выбора файлов отображает сведения для ориентации пользователей и обеспечивает согласованный интерфейс при открытии или сохранении файлов.

Эти сведения включают:

Текущее расположение
Элемент или элементы, выбранные пользователем
Дерево расположений, к которым пользователь может перейти. К этим расположениям относятся такие элементы файловой системы, как папка "Музыка" или "Загрузки", а также приложения, реализующие контракт средства выбора файлов, например, "Камера", "Фотографии" и "Microsoft OneDrive".

Возможно, у вас есть приложение, которое позволяет пользователям открывать или сохранять файлы. Когда пользователь инициирует это действие, приложение вызывает средство выбора файлов, которое отображает пользовательский интерфейс средства выбора файлов:

Снимок экрана: средство выбора открытых файлов с выбранным фильтром для отображения .txt, .pdf, .doc и .docx файлов.

Как элементы для выбора работают с вашим приложением

С помощью средства выбора приложение может получать доступ, просматривать и сохранять файлы и папки в системе пользователя. Приложение получает эти выборы как упрощенные объекты PickFileResult и PickFolderResult , которые предоставляют путь к выбранному файлу или папке.

Средство выбора использует единый унифицированный интерфейс, чтобы разрешить пользователю выбирать файлы и папки из файловой системы или из других приложений. Файлы, выбранные из других приложений, похожи на файлы из файловой системы. Как правило, приложение может работать с ними так же, как и другие объекты. Другие приложения предоставляют файлы с помощью участия в контрактах средства выбора файлов.

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

Выбор файла для открытия примера

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

using Microsoft.Windows.Storage.Pickers;

var openPicker = new FileOpenPicker(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 text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Open" (suitably translated).
    CommitButtonText = "Choose selected files",

    // (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
    FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },

    // (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
    ViewMode = PickerViewMode.List,
};

var result = await openPicker.PickSingleFileAsync();
if (result is not null)
{
    var content = System.IO.File.ReadAllText(result.Path);
}
else
{
    // Add your error handling here.
}

Это тот же пример в C++:

#include <winrt/Microsoft.Windows.Storage.Pickers.h>
#include <fstream>
#include <string>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FileOpenPicker openPicker(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.
openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);

// (Optional) specify the text displayed on the commit button. 
//     If not specified, the system uses a default label of "Open" (suitably translated).
openPicker.CommitButtonText(L"Choose selected files");

// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
openPicker.FileTypeFilter().ReplaceAll({ L".txt", L".pdf", L".doc", L".docx" });

// (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
openPicker.ViewMode(PickerViewMode::List);

auto result{ co_await openPicker.PickSingleFileAsync() };
if (result)
{
    std::ifstream fileReader(result.Path().c_str());
    std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
    winrt::hstring hText = winrt::to_hstring(text);
}
else
{
    // Add your error handling here.
}

Выбор нескольких файлов для открытия примера

Вы также можете разрешить пользователю выбирать несколько файлов. В следующем коде показано, как использовать класс FileOpenPicker , чтобы пользователь выбрал несколько файлов, таких как фотографии. Процесс такой же, но метод PickMultipleFilesAsync возвращает коллекцию путей к файлам вместо одного пути.

using Microsoft.Windows.Storage.Pickers;

var openPicker = new FileOpenPicker(this.AppWindow.Id);

var results = await openPicker.PickMultipleFilesAsync();
if (results.Count > 0)
{
    var pickedFilePaths = results.Select(f => f.Path);
    foreach (var path in pickedFilePaths)
    {
        var content = System.IO.File.ReadAllText(path);
    }
}
else
{
    // Add your error handling here.
}

Чтобы выполнить ту же операцию в C++, используйте следующий код:

#include <winrt/Microsoft.Windows.Storage.Pickers.h>
#include <fstream>
#include <string>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FileOpenPicker openPicker(this->AppWindow().Id());
auto results{ co_await openPicker.PickMultipleFilesAsync() };
if (results.Size() > 0)
{
    for (auto const& result : results)
    {
        std::ifstream fileReader(result.Path().c_str());
        std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
        winrt::hstring hText = winrt::to_hstring(text);
    }
}
else
{
    // Add your error handling here.
}

Выбор примера папки

Чтобы выбрать папку с помощью класса FolderPicker , используйте следующий код. Этот код создает средство выбора папок, отображает его пользователю с помощью метода PickSingleFolderAsync и извлекает путь выбранной папки в объекте PickFolderResult . Если пользователь выбирает папку, приложение извлекает путь к папке и сохраняет его в переменной для последующего использования.

using Microsoft.Windows.Storage.Pickers;

var folderPicker = new FolderPicker(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 text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Open" (suitably translated).
    CommitButtonText = "Select Folder",

    // (Optional) specify the view mode of the picker dialog. If not specified, default to List.
    ViewMode = PickerViewMode.List,
};

var result = await folderPicker.PickSingleFolderAsync();

if (result is not null)
{
    var path = result.Path;
}
else
{
    // Add your error handling here.
}

Чтобы выполнить ту же операцию в C++, используйте следующий код:

#include <winrt/Microsoft.Windows.Storage.Pickers.h>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FolderPicker folderPicker(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.
folderPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);

// (Optional) specify the text displayed on the commit button. 
//     If not specified, the system uses a default label of "Open" (suitably translated).
folderPicker.CommitButtonText(L"Select Folder");

// (Optional) specify the view mode of the picker dialog. If not specified, default to List.
folderPicker.ViewMode(PickerViewMode::List);

auto result{ co_await folderPicker.PickSingleFolderAsync() };
if (result)
{
    auto path{ result.Path() };
}
else
{
    // Add your error handling here.
}

Подсказка

Когда ваше приложение обращается к файлу или папке с помощью средства выбора, добавьте его в FutureAccessList или MostRecentlyUsedList, чтобы отслеживать его с помощью API среды выполнения Windows (WinRT). Дополнительные сведения см. в разделе "Отслеживание недавно используемых файлов и папок".

Пользовательский интерфейс средства выбора папок выглядит следующим образом:

Снимок экрана: средство выбора папок, просматривающий диск C.

Windows.Storage.Pickers

Файлы, папки и библиотеки с помощью пакета SDK для приложений Windows

Пространство имен Microsoft.Windows.Storage.Pickers

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-10-28