使用选取器打开文件和文件夹

重要的 API

• FileOpenPicker
• FolderPicker
• StorageFile

通过让用户与选取器交互来访问文件和文件夹。 你可以使用 FileOpenPicker 和 FileSavePicker 类访问文件，并使用 FolderPicker 访问文件夹。

注意

 有关完整示例，请参阅文件选取器示例。

注意

在桌面应用（包括 WinUI 3 应用）中，可以使用 Windows.Storage.Pickers 中的文件和文件夹选取器。 但是，如果桌面应用需要提升才能运行，则需要不同的方法，因为这些 API 不是为在提升的应用中使用而设计。 有关示例，请参阅FileSavePicker。

先决条件

• 了解通用 Windows 平台 (UWP) 应用的异步编程

  若要了解如何使用 C# 或 Visual Basic 编写异步应用，请参阅使用 C# 或 Visual Basic 调用异步 API。 若要了解如何使用 C++ 编写异步应用，请参阅使用 C++ 进行异步编程。

• 对位置的访问权限

  请参阅文件访问权限。

文件选取器 UI

文件选取器显示信息以引导用户并在打开或保存文件时提供一致性体验。

该信息包括：

• 当前位置
• 用户选取的项
• 用户可以浏览到的位置的树。 这些位置包括文件系统位置（如音乐或下载文件夹）以及实现文件选取器合约的应用（如相机、照片和 Microsoft OneDrive）。

电子邮件应用可能会显示文件选取器，以供用户选取附件。

选取器的工作原理

通过选取器，你的应用可以在用户的系统上访问、浏览以及保存文件和文件夹。 你的应用会接收这些选取项作为 StorageFile 和 StorageFolder 对象，然后你能在这些对象上进行操作。

选取器使用一个单一的统一界面，让用户从文件系统或从其他应用选取文件和文件夹。 从其他应用选取的文件与文件系统中的文件类似：它们是作为 StorageFile 对象返回的。 通常，你的应用可以按与其他对象相同的方式对它们进行操作。 其他应用通过参与文件选取器合约使文件可用。 如果你希望你的应用提供文件、保存位置或其他应用的文件更新，请参阅与文件选取器合约集成。

例如，你可能会在你的应用中调用文件选取器，以便你的用户可以打开文件。 这会使你的应用成为调用应用。 文件选取器与系统和/或其他应用交互来让用户导航和选取文件。 当你的用户选择文件时，文件选取器会将该文件返回到你的应用。 这里是从提供的应用（如 OneDrive）中选择文件所遇到的情形的过程。

选取单个文件：完成代码列表

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
picker.FileTypeFilter.Add(".jpg");
picker.FileTypeFilter.Add(".jpeg");
picker.FileTypeFilter.Add(".png");

Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
if (file != null)
{
    // Application now has read/write access to the picked file
    this.textBlock.Text = "Picked photo: " + file.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

选取单个文件：分步

使用文件选取器需要创建和自定义文件选取器对象，然后显示文件选取器，以使用户能选取一个或多个项目。

1. 创建和自定义 FileOpenPicker

   var picker = new Windows.Storage.Pickers.FileOpenPicker();
   picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
   picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
   picker.FileTypeFilter.Add(".jpg");
   picker.FileTypeFilter.Add(".jpeg");
   picker.FileTypeFilter.Add(".png");
   

   在文件选取器对象上设置与你的用户和应用相关的属性。

   此示例在某个方便的位置创建一种丰富的图片视觉显示，用户可以通过设置以下三个属性从该位置选取：ViewMode、SuggestedStartLocation 和 FileTypeFilter。

   • 将 ViewMode 设置为 PickerViewMode。Thumbnail 枚举值可通过使用图片缩略图创建丰富的视觉显示，以显示文件选取器中的文件。 此操作用于选取可视文件（如图片或视频）。 否则，请使用 PickerViewMode.List。 假定的电子邮件应用可在显示文件选取器之前设置适用于功能的 ViewMode，该应用具有附加图片或视频和附加文档功能。

   • 使用 PickerLocationId.PicturesLibrary 将 SuggestedStartLocation 设置为图片可让用户在他们有可能找到图片的某个位置开始。 将 SuggestedStartLocation 设置为适用于要选取的文件类型（例如音乐、图片、视频或文档）的位置。 用户可以从开始位置导航到其他位置。

   • 使用 FileTypeFilter 指定文件类型可保持用户专注于选取相关的文件。 若要将 FileTypeFilter 中以前的文件类型替换为新条目，请使用 ReplaceAll 而不是 Add。

2. 显示 FileOpenPicker

   • 选取单个文件

     Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
     if (file != null)
     {
         // Application now has read/write access to the picked file
         this.textBlock.Text = "Picked photo: " + file.Name;
     }
     else
     {
         this.textBlock.Text = "Operation cancelled.";
     }
     

   • 选取多个文件

     var files = await picker.PickMultipleFilesAsync();
     if (files.Count > 0)
     {
         StringBuilder output = new StringBuilder("Picked files:\n");
     
         // Application now has read/write access to the picked file(s)
         foreach (Windows.Storage.StorageFile file in files)
         {
             output.Append(file.Name + "\n");
         }
         this.textBlock.Text = output.ToString();
     }
     else
     {
         this.textBlock.Text = "Operation cancelled.";
     }
     

选取文件夹：完整代码列表

var folderPicker = new Windows.Storage.Pickers.FolderPicker();
folderPicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.Desktop;
folderPicker.FileTypeFilter.Add("*");

Windows.Storage.StorageFolder folder = await folderPicker.PickSingleFolderAsync();
if (folder != null)
{
    // Application now has read/write access to all contents in the picked folder
    // (including other sub-folder contents)
    Windows.Storage.AccessCache.StorageApplicationPermissions.
    FutureAccessList.AddOrReplace("PickedFolderToken", folder);
    this.textBlock.Text = "Picked folder: " + folder.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

提示

不论何时，只要应用通过选取器访问文件或文件夹，就将它添加到应用的 FutureAccessList 或 MostRecentlyUsedList 以便对进行跟踪。 你可以在如何跟踪最近使用的文件和文件夹中了解有关使用这些列表的详细信息。

另请参阅

Windows.Storage.Pickers

文件、文件夹和库

与文件选取器合约集成