快速入門：使用檔案選擇器存取檔案 (HTML)

發行項
12/11/2015

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱最新文件 ]

透過檔案選擇器，讓使用者挑選檔案和資料夾來存取檔案和資料夾。您可以使用 fileOpenPicker 類別來存取檔案，使用 folderPicker 來存取資料夾。

先決條件

了解使用 JavaScript 之 Windows 執行階段應用程式的非同步程式設計

您可以在快速入門：在 JavaScript 中使用 Promise 了解如何撰寫非同步應用程式。

檔案選擇器 UI

檔案選擇器在螢幕的頂端和底部都有顯示資訊的區域，可以在使用者存取或儲存檔案時為使用者指示方向和提供一致的使用體驗。

顯示的資訊包括：

目前的位置，位於左上方
使用者所選項目的置物籃，位於底部
使用者可以瀏覽的位置下拉式清單，可從左上方的向下箭號選取

例如，這個螢幕擷取畫面顯示為了讓使用者選擇一些檔案而呼叫的檔案選擇器。在螢幕擷取畫面中，使用者選取了兩個檔案。檔案選擇器的螢幕擷取，選取了兩個要開啟的檔案。

使用者只要選取檔案選擇器左上角的向下箭號，就可以檢視可用位置的下拉式清單 (如右邊螢幕擷取畫面中所示的清單)。這些位置包括系統位置，如 [音樂] 或 [下載] 資料夾。它們也包含其他參與了檔案選擇器協定的應用程式 (像是 Microsoft OneDrive)，如螢幕擷取畫面中清單的底部所示。

挑選一個檔案的完整程式碼

檔案選擇器範例會示範如何使用 fileOpenPicker 讓使用者挑選單一檔案。

// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);

// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

如需挑選多個檔案的完整程式碼，請參閱檔案選擇器範例。

挑選一個檔案的逐步解說

呼叫檔案選擇器需要兩個基本工作：建立和自訂檔案選擇器物件，以及顯示檔案選擇器供使用者挑選項目。

建立和自訂 FileOpenPicker

如果使用者挑選一或多個檔案，請使用 fileOpenPicker。在您建立的物件上設定屬性，即可自訂這個類別。

檔案選擇器範例會示範如何建立和自訂 fileOpenPicker。
```
// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
您應該在與使用者和您應用程式相關的檔案選擇器物件上設定屬性。如需協助您決定如何自訂檔案選擇器的指導方針，請參閱檔案選擇器的指導方針和檢查清單。如需為什麼我們要在檔案選擇器範例中設定特定屬性以自訂檔案選擇器的說明，請繼續讀下去。

檔案選擇器範例 FileOpenPicker 自訂的詳細說明

檔案選擇器範例會設定下列三個 fileOpenPicker 屬性，在使用者可以挑選的便利位置建立一個豐富的視覺化圖片：viewMode、suggestedStartLocation 以及 fileTypeFilter 屬性。
- 將 openPicker.viewMode 設定成 thumbnail PickerViewMode 列舉值會建立一個豐富的視覺顯示，這樣做會在檔案選擇器中使用圖片縮圖表示檔案。
```
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
  如果您要使用檔案選擇器來顯示圖片或影片等視覺檔案，應該考慮將 viewMode 設定成 PickerViewMode.thumbnail。否則，請使用 PickerViewMode.list。
  
  在某些情況下，使用者可能想要挑選圖片或影片或任何其他檔案類型。例如，使用者可能會挑選要附加到電子郵件或透過 IM 傳送的檔案。在這種情形下，您應該新增兩個 UI 控制項到您的應用程式來支援這兩種檢視模式。一個控制項應該使用 thumbnail 檢視模式來呼叫檔案選擇器，如此一來，使用者就可以挑選圖片和影片。另一個控制項應該使用 list 檢視模式來呼叫檔案選擇器，如此一來，使用者就可以挑選其他類型的檔案。例如，電子郵件應用程式可以有兩個按鈕：[附加圖片或影片] 和 [附加文件]****。
- 使用 PickerLocationId.picturesLibrary 將 openPicker.suggestedStartLocation 設定為 [圖片]，讓使用者從想要尋找圖片的位置開始尋找。
```
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
```
  您應該將 suggestedStartLocation 設定成所挑選之檔案類型適用的檔案系統位置。如果使用者要挑選音樂、圖片或影片，請將開始位置分別設定為 [音樂]、[圖片] 或 [影片]。對於所有其他類型的檔案，請將開始位置設定為 [文件]。這只是開始的位置。使用者使用檔案選擇器時可以瀏覽到其他位置。
  
  此外，suggestedStartLocation 不一定永遠是檔案選擇器的開始位置。為了讓使用者享有一致的使用經驗，檔案選擇器會記住使用者上次檢視的位置，並從該位置開始。
- 使用 openPicker.fileTypeFilter.replaceAll 指定使用者可以在檔案選擇器中看到的檔案類型，這樣做可讓使用者專注在挑選相關和可用的檔案上。
```
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
  您應該考慮在檔案選擇器中指定要顯示的檔案類型，以便只顯示相關的檔案。例如，如果您的應用程式是影片播放程式，您可以使用 fileTypeFilter 屬性，確保檔案選擇器中顯示的是播放程式支援的影片格式檔案 (根據影片檔案副檔名)。
  
  如果您想要將檔案類型新增到 fileTypeFilter 而不是取代項目，可以使用 append 方法 (而不是 replaceAll)。
顯示 FileOpenPicker

現在您可以顯示檔案選擇器，讓使用者挑選單一檔案或多個檔案：
- 顯示檔案選擇器以供使用者挑選單一檔案
  
  建立和自訂檔案選擇器後，呼叫 fileOpenPicker.pickSingleFileAsync 以供使用者挑選一個檔案。使用者挑選檔案時，fileOpenPicker.pickSingleFileAsync 會傳回一個代表選中檔案的 storageFile 物件。
  
  檔案選擇器範例會示範如何顯示檔案選擇器讓使用者挑選一個檔案，以及如何擷取選取檔案進行處理。
```
// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  當 openPicker.pickSingleFileAsync 呼叫完成時，選中的檔案 (由 storageFile 物件表示) 會傳遞到函式常值當作 file 參數處理。如果操作被取消且沒有挑選任何項目，這個參數將會是 null。
- 顯示檔案選擇器以供使用者挑選多個檔案
  
  建立和自訂檔案選擇器後，呼叫 fileOpenPicker.pickMultipleFilesAsync 以供使用者挑選多個檔案。
  
  使用者挑選多個檔案時，fileOpenPicker.pickMultipleFilesAsync 會傳回代表選中檔案的 storageFile 物件清單。
  
  檔案選擇器範例會示範如何顯示檔案選擇器讓使用者挑選多個檔案，以及如何擷取選中之檔案的清單進行處理。
```
openPicker.pickMultipleFilesAsync().then(function (files) {
    if (files.size > 0) {
        // Application now has read/write access to the picked file(s)
        var outputString = "Picked files:\n";
        for (var i = 0; i < files.size; i++) {
            outputString = outputString + files[i].name + "\n";
        }
        WinJS.log && WinJS.log(outputString, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  當 openPicker.pickMultipleFilesAsync 呼叫完成時，選中的檔案清單會傳遞到函式常值當作 files 參數處理。清單中挑選的檔案會以 storageFile 物件表示。如果操作被取消且沒有挑選任何項目，這個參數的大小將會大於 0。

挑選一個資料夾的完整程式碼

檔案選擇器範例會示範如何使用 folderPicker 讓使用者挑選單一資料夾。

// Verify that we are currently not snapped, or that we can unsnap to open the picker
var currentState = Windows.UI.ViewManagement.ApplicationView.value;
if (currentState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
    !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
    // Fail silently if we can't unsnap
    return;
}

// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);

folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

挑選一個資料夾的逐步解說

呼叫檔案選擇器需要兩個基本工作：建立和自訂檔案選擇器物件，以及顯示檔案選擇器供使用者挑選項目。

建立和自訂 folderPicker

如果使用者挑選一個資料夾，請使用 folderPicker。在您建立的物件上設定屬性，即可自訂這個類別。

檔案選擇器範例會示範如何建立和自訂 folderPicker。
```
// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
您應該在與使用者和您應用程式相關的檔案選擇器物件上設定屬性。如需協助您決定如何自訂檔案選擇器的指導方針，請參閱檔案選擇器的指導方針和檢查清單。如需為什麼我們要在檔案選擇器範例中設定特定屬性以自訂檔案選擇器的說明，請繼續讀下去。

檔案選擇器範例 folderPicker 自訂的詳細說明

檔案選擇器範例使用三個 folderPicker 屬性自訂檔案選擇器以挑選資料夾：viewMode、suggestedStartLocation 以及 fileTypeFilter 屬性。
- 使用 folderPicker.viewMode 的預設 PickerViewMode.list 可以讓我們在檔案選擇器中建立清單式顯示。這個清單很適合用來選取非視覺檔案 (如文件)。
  
  如果您要使用檔案選擇器來顯示圖片或影片等視覺檔案，應該考慮將 viewMode 設定成 PickerViewMode.thumbnail。否則，請使用 PickerViewMode.list。
  
  如果您要顯示圖片或影片之類的視覺檔案，應該將 folderPicker.viewMode 設定成 thumbnail，像這樣：
```
folderPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
- 使用 PickerLocationId.desktop 將 folderPicker.suggestedStartLocation 設定為使用者的桌面，讓使用者可以從熟悉的常用位置開始使用。
```
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
```
  您應該根據使用者要挑選的資料夾類型，將 suggestedStartLocation 設定成適當的檔案系統位置。例如，如果使用者要挑選包含音樂檔的資料夾，您應該讓他們從 [音樂] 開始。這只是開始的位置：使用者使用檔案選擇器時可以瀏覽到其他位置。
  
  此外，suggestedStartLocation 不一定永遠是檔案選擇器的開始位置。為了讓使用者享有一致的使用經驗，檔案選擇器會記住使用者上次檢視的位置，並從該位置開始。
- 使用 folderPicker.fileTypeFilter.replaceAll 指定使用者可以在檔案選擇器中看到的檔案類型，這樣做可讓使用者專注在挑選相關的資料夾上。
```
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  使用者只可以透過 folderPicker 選取資料夾，無法選取個別檔案。不過，在 folderPicker 中顯示相關檔案可協助使用者判定他們想要選取的資料夾。例如，使用 folderPicker 選取一個位置來匯入圖片時，顯示影像檔案可以協助使用者識別選取這個位置時將匯入的項目。
顯示 folderPicker 以供使用者挑選單一資料夾

建立和自訂 folderPicker 後，呼叫 folderPicker.pickSingleFolderAsync 以供使用者挑選一個資料夾。使用者挑選資料夾時，folderPicker.pickSingleFolderAsync 會傳回一個代表選中資料夾的 storageFolder。您應該使用 done 擷取和處理這個資料夾，以便正確傳播例外狀況。

檔案選擇器範例會示範如何顯示檔案選擇器讓使用者挑選一個資料夾，以及如何擷取選中的資料夾進行處理。
```
folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
當 folderPicker.pickSingleFolderAsync 呼叫完成時，選中的資料夾會傳遞到函式當作 folder 參數處理。選中的資料夾是由 storageFolder 物件表示。如果操作被取消且沒有挑選任何項目，這個參數將會是 null。

摘要與後續步驟

如果您使用和這裡類似的程式碼，您的應用程式將會顯示檔案選擇器，讓使用者挑選應用程式可以開啟的一或多個檔案或資料夾。

秘訣只要您的應用程式透過檔案選擇器來存取檔案或資料夾，就會將該項目新增到應用程式的 futureAccessList 或 mostRecentlyUsedList 以便追蹤。若要深入了解如何使用這些清單，請參閱如何追蹤最近使用的檔案和資料夾。

若要深入了解讀取和寫入檔案，請參閱快速入門：讀取和寫入檔案以及檔案存取範例。若要深入了解使用影像檔案，請參閱如何選取和顯示影像、如何解碼影像以及使用 Blob 儲存和載入內容範例。

若要深入了解如何呼叫檔案選擇器來儲存檔案，請參閱如何透過檔案選擇器儲存檔案。

如果您想要應用程式提供檔案、儲存位置或檔案更新給其他應用程式，請參閱快速入門：與檔案選擇器協定整合。