Guia de início rápido: acessando o conteúdo do Grupo Doméstico (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

O conteúdo de acesso é armazenado na pasta Grupo Doméstico do usuário, incluindo imagens, música e vídeos.

Pré-requisitos

Entender a programação assíncrona dos aplicativos do Tempo de Execução do Windows em JavaScript

Você pode aprender como escrever aplicativos assíncronos em Guia de início rápido: usando promessas em JavaScript.
Declarações de recursos do aplicativo

Para acessar o conteúdo do Grupo Doméstico, a máquina do usuário deverá ter um Grupo Doméstico configurado e seu aplicativo deve ter pelo menos um dos seguintes recursos: biblioteca de Imagem, biblioteca de Músicas ou biblioteca de Vídeos. Quando seu aplicativo acessar a pasta Grupo Doméstico, ele verá somente as bibliotecas correspondentes aos recursos declarados em seu manifesto do aplicativo. Saiba mais sobre essas funcionalidades em Declarações de funcionalidades de aplicativos.

Observação O conteúdo na pasta Documentos de um Grupo Doméstico não fica visível para seu aplicativo independentemente dos recursos declarados em seu manifesto do aplicativo e independente das configurações de compartilhamento do usuário.
Noções básicas para usar seletores de arquivos

Normalmente, você usa o seletor de arquivos para acessar arquivos e pastas no Grupo Doméstico. Para aprender como usar o seletor de arquivos, veja Guia de início rápido: acessando arquivos com os seletores de arquivos.
Noções básicas sobre consultas de arquivo e pasta

Você pode usar consultas para enumerar arquivos e pastas no Grupo Doméstico. Para saber mais sobre as consultas de arquivo e pasta, veja Guia de início rápido: acessando arquivos programaticamente.

Abrir o seletor de arquivos no Grupo Doméstico

Siga essas etapas para abrir uma instancia do seletor de arquivos que permite que o usuário selecione arquivos e pastas a partir do Grupo Doméstico:

Criar e personalizar o seletor de arquivos

Use o fileOpenPicker para criar o seletor de arquivos e defina o SuggestedStartLocation do seletor como PickerLocationId.homeGroup. Além disso, defina outras propriedades que sejam relevantes para seus usuários e seu aplicativo. Para obter diretrizes para ajudá-lo a decidir como personalizar o seletor de arquivos, consulte Diretrizes e lista de verificação para os seletores de arquivos

Este exemplo cria um seletor de arquivos que abre no Grupo Doméstico, inclui os arquivos de qualquer tipo e exibe os arquivos como imagens em miniatura:
```
var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll(["*"]);
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```

Mostrar o seletor de arquivos.

Após criar e personalizar um seletor de arquivos, permita que o usuário selecione um arquivo chamando fileOpenPicker.pickSingleFileAsync. Ou, permita que selecionem vários arquivos chamando fileOpenPicker.pickMultipleFilesAsync.

Este exemplo mostra como exibir o seletor de arquivos para permitir que o usuário selecione um arquivo e como capturar o arquivo selecionado para processamento.

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");
});

Pesquisar o Grupo Doméstico para arquivos

Esta seção mostra como encontrar itens do Grupo Doméstico correspondentes a um termo da consulta fornecido pelo usuário.

Obter o termo da consulta do usuário.

Aqui obtemos um termo de consulta que o usuário inseriu em um campo de entrada:
```
var query = document.getElementById("queryString").value;
```

Defina as opções de consulta e o filtro de pesquisa.

As opções de consulta determinam como os resultados da pesquisa são classificados, enquanto o filtro de pesquisa determina quais itens são incluídos nos resultados da pesquisa.

Este exemplo define as opções de consulta que classificam os resultados da pesquisa por importância e depois a data é modificada. O filtro de pesquisa é o termo da consulta que o usuário inseriu na etapa anterior:

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

Execute a consulta e processe os resultados.

O exemplo a seguir executa a consulta da pesquisa e salva os nomes de quaisquer arquivos correspondentes como uma lista de cadeia de caracteres.

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");
}

Pesquise o Grupo Doméstico para obter arquivos compartilhados de um usuário específico

Esta seção mostra a você como encontrar arquivos do Grupo Doméstico compartilhados por um usuário específico.

Obtenha uma coleção de usuários do Grupo Doméstico.

Cada uma das pastas de primeiro nível no Grupo Doméstico representa um usuário do Grupo Doméstico individual. Portanto, para obter a coleção de usuários do Grupo Doméstico, chame a recuperação das pastas do Grupo Doméstico de nível superior GetFoldersAsynce, em seguida, itere por meio das pastas recuperadas para obter os usuários individuais.
```
var hg = Windows.Storage.KnownFolders.homeGroup;
hg.getFoldersAsync().then(function (users) {
    users.forEach(function (user) {

    // TODO: Do something with the user name. 

    });
}
```
Crie uma consulta de arquivo e defina o seu escopo para um usuário específico.

O exemplo a seguir define as opções de consulta que classificam os resultados da pesquisa por importância e depois pela data modificada. As opções de consulta são aplicadas em uma consulta de pesquisa com escopo para um usuário particular.
```
var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
var query = user.createFileQueryWithOptions(options);
```

Execute a consulta e processe os arquivos resultantes.

Esse exemplo executa a consulta da pesquisa e salva os nomes dos arquivos correspondentes a um determinado usuário, como uma lista de cadeia de caracteres.

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");
        });
    }
});

Transmitir vídeo a partir do Grupo Doméstico

Siga essas etapas para transmitir o conteúdo do vídeo a partir do Grupo Doméstico:

Inclua um elemento de vídeo em uma página HTML do aplicativo.

O elemento do video especifica o conteúdo de vídeo para ser reproduzido em seu aplicativo.

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

Abra um seletor de arquivos no Grupo Doméstico e aplique um filtro que inclua os arquivos de vídeo nos formatos compatíveis com seu aplicativo.

Este exemplo inclui arquivos .mp4 e .wmv no seletor de arquivos aberto.

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"]);

Converta a seleção do arquivo do usuário em uma URL e defina a URL como a origem do elemento de vídeo.

O exemplo a seguir recupera o elemento de vídeo e o inicia para ficar invisível e no estado pausado. Depois que o usuário escolhe um arquivo de vídeo, o exemplo recupera a URL do arquivo, a define como a origem do elemento video, mostra o elemento de vídeo e inicia a reprodução do vídeo.

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");
});