使用選擇器開啟檔案和資料夾

重要 API

• FileOpenPicker \(英文\)
• FolderPicker \(英文\)
• StorageFile

讓使用者與選擇器互動以存取檔案和資料夾。 您可以使用 FileOpenPicker 和 FileSavePicker 類別來存取檔案，使用 FolderPicker 來存取資料夾。

注意

 如需完整範例，請參閱檔案選擇器範例 \(英文\)。

注意

注意：在桌面應用程式中 (包含 WinUI 3 應用程式)，您可以使用 Windows.Storage.Pickers 中的檔案和資料夾選擇器。 不過，如果桌面應用程式需要提升權限才能執行，您將需要不同的方法，因為這些 API 並非設計用於提升權限的應用程式。 如需範例，請參閱 FileSavePicker。

必要條件

• 了解通用 Windows 平台 (UWP) 應用程式的非同步程式設計

  您可以參閱在 C# 或 Visual Basic 中呼叫非同步 API，以了解如何使用 C# 或 Visual Basic 撰寫非同步的應用程式。 若要了解如何使用 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

檔案、資料夾和媒體櫃

與檔案選擇器合約整合