快速入门：访问家庭组内容 (HTML)

项目
12/11/2015

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅最新文档 ]

访问存储在用户的“家庭组”文件夹中的内容，包括图片、音乐和视频。

先决条件

了解使用 JavaScript 的 Windows 运行时应用的异步编程

在快速入门：在 JavaScript 中使用承诺中了解如何编写异步应用。
应用功能声明

若要访问家庭组内容，用户的计算机必须已设置家庭组，且你的应用必须至少具有以下功能之一：图片库、音乐库或视频库。当你的应用获取“家庭组”文件夹之后，它将仅看到与你在你的应用的清单中声明的功能相对应的库。在应用功能声明中，了解有关这些功能的更多信息。

注意无论在你的应用的清单中声明了什么功能，也无论用户的共享设置如何，你的应用都看不到家庭组的文档文件夹中的内容。
了解如何使用文件选取器

你通常使用文件选取器来访问家庭组中的文件和文件夹。要了解如何使用文件选取器，请参阅快速入门：使用文件选取器访问文件。
了解文件和文件夹查询

你可以使用查询来枚举家庭组中的文件和文件夹。要了解有关文件和文件夹查询的信息，请参阅快速入门：以编程方式访问文件。

在家庭组打开文件选取器

按以下步骤打开文件选取器的一个实例，让用户从家庭组中选取文件和文件夹：

创建并自定义文件选取器

使用 fileOpenPicker 创建文件选取器，然后将选取器的 SuggestedStartLocation 设置为 PickerLocationId.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");
});

在家庭组中搜索文件

此部分显示了如何找到与用户提供的查询词匹配的家庭组项目。

从用户获取查询词。

下面我们将获取一个用户已输入到某个输入字段中的查询词：
```
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");
}

在家庭组中搜索某个特定用户的共享文件

此部分介绍如何查找由特定用户共享的家庭组文件。

获取家庭组用户的集合。

家庭组中每个第一级文件夹表示单个家庭组用户。因此，要获取家庭组用户的集合，请调用 GetFoldersAsync 检索顶级家庭组文件夹，然后循环访问检索的文件夹以获取单个用户。
```
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");
        });
    }
});

从家庭组流式传输视频

请按以下步骤从家庭组流式传输视频内容：

在应用 HTML 页面中包含一个视频元素。

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>

在家庭组打开某个文件选取器，并应用某个筛选器，该筛选器包含采用你的应用支持的格式的视频文件。

此示例在文件打开选取器中包含 .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 设置为视频元素的源。

以下示例检索视频元素并初始化它以使其不可见并处于暂停状态。在用户选择某个视频文件之后，该示例将检索该文件的 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");
});

摘要

你现在应该已了解如何访问家庭组中的内容了。

通过