Guida introduttiva: Accesso al contenuto del Gruppo Home (HTML)

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Puoi accedere al contenuto archiviato nella cartella Gruppo Home dell'utente, che include immagini, musica e video.

Prerequisiti

Conoscere le tecniche di programmazione asincrona per le app di Windows Runtime che usano JavaScript

Per informazioni su come scrivere app asincrone, vedi Guida introduttiva: Uso delle promesse in JavaScript.
Dichiarazioni di funzionalità delle app

Per accedere al contenuto del Gruppo Home, nel computer dell'utente deve essere configurato un Gruppo Home e la tua app deve avere almeno una delle funzionalità seguenti: Raccolta di immagini, Catalogo musicale o Catalogo video Quando l'app accede alla cartella Gruppo Home, visualizzerà solo le raccolte e i cataloghi che corrispondono alle funzionalità da te dichiarate nel manifesto dell'app. Per altre informazioni su queste funzionalità, vedi Dichiarazioni di funzionalità delle app.

Nota Il contenuto della cartella Documenti di un gruppo home non è visibile per l'app, a prescindere dalle funzionalità dichiarate nel manifesto dell'app e dalle impostazioni di condivisione dell'utente.
Conoscere e saper usare le selezioni file

Normalmente la selezione file viene usata per accedere ai file e alle cartelle nel gruppo home. Per informazioni sull'uso della selezione file, vediGuida introduttiva: Accesso ai file mediante le selezioni file.
Conoscere le query su file e cartelle

Le query vengono usate per enumerare i file e le cartelle nel Gruppo Home. Per informazioni sull'uso delle query su file e cartelle, vedi Guida introduttiva: Accesso ai file a livello di codice.

Apertura della selezione file per il Gruppo Home

Esegui questi passaggi per aprire un'istanza della selezione file che consenta all'utente di selezionare file e cartelle dal Gruppo Home:

Creare e personalizzare la selezione file

Usa fileOpenPicker per creare la selezione file, quindi imposta il percorso SuggestedStartLocation su PickerLocationId.homeGroup. Imposta anche le altre proprietà che sono pertinenti per i tuoi utenti e per la tua app. Per indicazioni su come personalizzare la selezione file, vedi Linee guida ed elenco di controllo per la selezione file.

Questo esempio crea una selezione file che si apre specificamente per il Gruppo Home, include file di tutti i tipi e li visualizza come immagini di anteprima:
```
var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll(["*"]);
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```

Visualizzare la selezione file.

Dopo avere creato e personalizzato la selezione file, consenti all'utente di selezionare un solo file chiamando fileOpenPicker.pickSingleFileAsync o più file chiamando fileOpenPicker.pickMultipleFilesAsync.

L'esempio mostra come visualizzare la selezione file per consentire all'utente di selezionare un unico file e come acquisire il file selezionato per l'elaborazione:

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

Ricerca dei file nel Gruppo Home

Questa sezione spiega come trovare gli elementi del Gruppo Home che corrispondono a un termine della query specificata dall'utente.

Recuperare il termine della query dall'utente.

L'esempio seguente recupera un termine della query che l'utente ha inserito in un campo di input:
```
var query = document.getElementById("queryString").value;
```

Impostare le opzioni della query e il filtro di ricerca.

Le opzioni della query determinano l'ordine in cui vengono presentati i risultati della ricerca, mentre il filtro di ricerca determina quali elementi sono inclusi nei risultati.

L'esempio seguente imposta le opzioni della query per ordinare i risultati della ricerca in base alla loro pertinenza e poi in base alla data di modifica. Il filtro di ricerca è il termine della query che l'utente ha inserito nel passaggio precedente:

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

Eseguire la query ed elaborare i risultati.

L'esempio seguente esegue la query di ricerca e salva i nomi di tutti i file corrispondenti come un elenco di stringhe.

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

Cercare nel Gruppo Home i file condivisi di un particolare utente

Questa sezione illustra come trovare i file del Gruppo Home condivisi da un particolare utente.

Recupera una raccolta degli utenti del Gruppo Home.

Ognuna delle cartelle di primo livello nel Gruppo Home rappresenta un singolo utente del Gruppo Home. Per recuperare la raccolta degli utenti del Gruppo Home, quindi, chiama GetFoldersAsync per recuperare le cartelle di primo livello del Gruppo Home e quindi esegui un'iterazione delle cartelle recuperate per ottenere i singoli utenti.
```
var hg = Windows.Storage.KnownFolders.homeGroup;
hg.getFoldersAsync().then(function (users) {
    users.forEach(function (user) {

    // TODO: Do something with the user name. 

    });
}
```
Crea una query su file con un utente specifico come ambito.

L'esempio seguente imposta le opzioni della query per ordinare i risultati della ricerca prima in base alla loro pertinenza e poi in base alla data di modifica. Le opzioni della query vengono poi applicate a una query di ricerca con un utente specifico come ambito.
```
var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
var query = user.createFileQueryWithOptions(options);
```

Esegui la query ed elabora i file risultanti.

L'esempio seguente esegue la query di ricerca e salva i nomi dei file corrispondenti all'utente specificato, come un elenco di stringhe.

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

Acquisizione video dal Gruppo Home

Esegui questi passaggi per acquisire contenuto video dal Gruppo Home:

Includere un elemento video in una pagina HTML dell'app.

L'elemento video specifica il contenuto video da riprodurre nell'app.

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

Aprire una selezione file per il Gruppo Home e applicare un filtro che includa i file video tra i formati supportati dall''app.

L'esempio seguente include i formati mp4 e wmv nella selezione per apertura file.

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

Convertire la selezione di file effettuata dall'utente in un URL, quindi impostare l'URL come origine dell'elemento video.

L'esempio seguente recupera l'elemento video e lo inizializza in modo che sia invisibile e nello stato di pausa. Dopo che l'utente sceglie un file video, l'esempio recupera l'URL del file, lo imposta come origine per l'elemento video, rende visibile l'elemento video e inizia a riprodurlo.

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