快速入門：存取 HomeGroup 內容 (HTML)

發行項
12/11/2015

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

存取儲存在使用者 HomeGroup 資料夾中的內容，包括圖片、音樂及視訊。

先決條件

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

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

若要存取 HomeGroup 內容，使用者的電腦必須設定 HomeGroup，而且您的應用程式必須至少具有下列其中一項功能：圖片庫、音樂庫或視訊庫。當您的應用程式取得 HomeGroup 資料夾時，它將只會看到與您在應用程式資訊清單中宣告之功能對應的媒體櫃。您可以在應用程式功能宣告深入了解這些功能。

注意無論應用程式資訊清單中是否宣告了這些功能，或是使用者是否使用分享設定，您的應用程式都看不到 HomeGroup [文件] 資料夾中的內容。
了解如何使用檔案選擇器

您通常會使用檔案選擇器來存取 HomeGroup 中的檔案和資料夾。若要深入了解如何使用檔案選擇器，請參閱快速入門：使用檔案選擇器存取檔案。
了解檔案和資料夾查詢

您可以使用查詢來列舉 HomeGroup 中的檔案和資料夾。若要深入了解檔案和資料夾查詢，請參閱快速入門：以程式設計方式存取檔案。

在 HomeGroup 開啟檔案選擇器

遵循下列步驟開啟檔案選擇器的執行個體，讓使用者從 HomeGroup 挑選檔案檔案和資料夾：

建立和自訂檔案選擇器

使用 fileOpenPicker 建立檔案選擇器，然後將選擇器的 SuggestedStartLocation 設定成 PickerLocationId.homeGroup。另外，設定與您的使用者和應用程式相關的其他屬性。如需協助您決定如何自訂檔案選擇器的指導方針，請參閱檔案選擇器的指導方針和檢查清單。

這個範例會建立在 HomeGroup 開啟的檔案選擇器 (包含任何檔案類型)，並以縮圖影像顯示檔案：
```
var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll(["*"]);
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```

顯示檔案選擇器。

建立和自訂檔案選擇器後，呼叫 fileOpenPicker.pickSingleFileAsync 以供使用者挑選一個檔案。或者，呼叫 fileOpenPicker.pickMultipleFilesAsync 讓他們挑選多個檔案。

這個範例會示範如何顯示檔案選擇器讓使用者挑選一個檔案，以及如何擷取所選的檔案進行處理。

picker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // The app now has read/write access to the picked file.
        WinJS.log && WinJS.log("1 file selected: \"" + file.path + "\"", 
            "sample", "status");

        // If the returned file was an image, show it to the user.
        if ((".JPG" === file.fileType) || (".jpg" === file.fileType) || 
            (".JPEG" === file.fileType) || (".jpeg" === file.fileType) || 
            (".PNG" === file.fileType) || (".png" === file.fileType) || 
            (".BMP" === file.fileType) || (".bmp" === file.fileType)) {
                document.getElementById("returnedImage").src = 
                    URL.createObjectURL(file, { oneTimeOnly: true });
                document.getElementById("returnedImage").style.visibility = "visible";
        } else {
            // The returned file wasn't an image, so hide the container where it 
            // would have appeared.
            document.getElementById("returnedImage").style.visibility = "hidden";
        }
    }
},

function (file) {
    // An error occurred.
    WinJS.log && WinJS.log("File was not returned", "sample", "error");
});

搜尋 HomeGroup 中的檔案

本節示範如何尋找符合使用者查詢字詞的 HomeGroup 項目。

從使用者取得查詢字詞。

在這裡我們要取得使用者在輸入欄位中輸入的查詢字詞：
```
var query = document.getElementById("queryString").value;
```

設定查詢選項和搜尋篩選。

查詢選項會決定搜尋結果的排序方式，而搜尋篩選則會決定搜尋結果中會包含的項目。

這個範例會設定先以相關性再以修改日期來排序搜尋結果的查詢選項。搜尋篩選是使用者在前面步驟中輸入的查詢字詞：

var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
options.userSearchFilter = query;

執行查詢並處理結果。

下列範例會執行搜尋查詢，並將任何相符的檔案名稱儲存為字串清單。

try {
    var queryResult = 
        Windows.Storage.KnownFolders.homeGroup.createFileQueryWithOptions(options);

    queryResult.getFilesAsync().then(function (files) {
        // If no matching files were found, show appropriate output and turn 
        // off the progress ring.
        if (files.size === 0) {
            WinJS.log && WinJS.log("No files found for \"" + query + "\"", 
                "sample", "status");
            document.getElementById("searchProgress").style.visibility = "hidden";
        }

        // We found matching files. Show them and turn off the progress ring.
        else {
            var outputString = (files.size === 1) ? 
                (files.size + " file found\n") : (files.size + " files found\n");
            files.forEach(function (file) {
                outputString = outputString.concat(file.name, "\n");
            });
            WinJS.log && WinJS.log(outputString, "sample", "status");
            document.getElementById("searchProgress").style.visibility = "hidden";
        }
    });
}
catch (e) {
    // An error occurred. Show and log the error.
    document.getElementById("searchProgress").style.visibility = "hidden";
    WinJS.log && WinJS.log(e.message, "sample", "error");
}

搜尋 HomeGroup 中特定使用者的分享檔案

本節說明如何尋找由特定使用者分享的 HomeGroup 檔案。

取得 HomeGroup 使用者的集合。

HomeGroup 中的每個第一層資料夾都代表不同的 HomeGroup 使用者。因此，若要取得 HomeGroup 使用者的集合，請呼叫 GetFoldersAsync 擷取最上層 HomeGroup 資料夾，然後逐一查看所擷取的資料夾以尋找個別使用者。
```
var hg = Windows.Storage.KnownFolders.homeGroup;
hg.getFoldersAsync().then(function (users) {
    users.forEach(function (user) {

    // TODO: Do something with the user name. 

    });
}
```
建立一個檔案查詢，並將其範圍設定為特定使用者。

下列範例會設定先以相關性，再以修改日期來排序搜尋結果的查詢選項。然後查詢選項會套用到範圍設為特定使用者的搜尋查詢。
```
var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
var query = user.createFileQueryWithOptions(options);
```

執行查詢並處理產生的檔案。

這個範例會執行搜尋查詢，並將符合特定使用者的檔案名稱儲存為字串清單。

query.getFilesAsync().then(function (files) {

    // If we don't find any shared files for the specified user, 
    // hide the progress indicator and notify the user. 
    if (files.size === 0) {
        document.getElementById("searchProgress").style.visibility = "hidden";

        // In the following line, userToSearch is a name specified by
        // the app user.
        outputString = "No files shared by " + userToSearch + ""; 
    }

    // We found shared files for this user. Hide the progress indicator
    // and process the files.  
    else {
        document.getElementById("searchProgress").style.visibility = "hidden";
        outputString = (files.size === 1) ? 
            (files.size + " file found\n") : (files.size + " files shared by ");
        outputString = outputString.concat(userToSearch, "\n");
        files.forEach(function (file) {
            outputString = outputString.concat(file.name, "\n");
        });
    }
});

從 HomeGroup 串流視訊

遵循這些步驟從 HomeGroup 串流視訊內容：

在應用程式 HTML 網頁中包含 video 元素。

video 元素指定要在您應用程式中播放的視訊內容。

<div data-win-control="SdkSample.ScenarioOutput">
    <video id="player" height="338" width="600" controls style="visibility: hidden">Unable to play video file</video>
</div>

在 HomeGroup 開啟檔案選擇器，套用包含您應用程式支援的視訊檔案格式的篩選。

這個範例在檔案開啟選擇器中包含了 .mp4 和 .wmv 檔案。

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll([".mp4", ".wmv"]);

將使用者選取的檔案轉換為 URL，然後將 URL 設定為 video 元素的來源。

下面的範例會抓取 video 元素，並將它初始化為不可見及暫停狀態。使用者選擇視訊檔案之後，範例會抓取檔案的 URL，將它設定為 video 元素的來源，顯示視訊元素，然後開始播放視訊。

var vidPlayer = document.getElementById("player");
vidPlayer.style.visibility = "hidden";
vidPlayer.pause();
picker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // The video tag has built in capabilities to stream the video over 
        // the network.
        vidPlayer.src = URL.createObjectURL(file, { oneTimeOnly: true });
        vidPlayer.style.visibility = "visible";
        vidPlayer.play();
    }
},
function (file) {
    WinJS.log && WinJS.log("File was not returned", "sample", "error");
});

摘要

您現在應該了解如何存取 HomeGroup 中的內容。

共用方式為