Démarrage rapide : accès au contenu Groupement résidentiel (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Accédez au contenu stocké dans le dossier Groupement résidentiel de l’utilisateur, qui contient des images, de la musique et des vidéos.

Prérequis

Comprendre la programmation asynchrone pour les applications Windows Runtime en JavaScript

Pour apprendre à écrire des applications asynchrones, voir Démarrage rapide : utilisation de promesses (« promises ») dans JavaScript.
Déclarations des fonctionnalités d’application

Pour accéder au contenu Groupement résidentiel, l’ordinateur de l’utilisateur doit avoir un Groupement résidentiel configuré et votre application au moins une des fonctionnalités suivantes : bibliothèque Images, bibliothèque Musique ou bibliothèque Vidéos. Lorsque votre application accédera au dossier Groupement résidentiel, il ne verra que les bibliothèques correspondant aux fonctionnalités déclarées dans le manifeste de votre application. Découvrez tout ce qu’il faut savoir sur ces fonctionnalités dans Déclarations des fonctionnalités d’application.

Remarque Le contenu du dossier Documents d’un Groupement résidentiel n’est pas visible pour votre application quelles que soient les fonctionnalités déclarées dans le manifeste de votre application et quels que soient les paramètres de partage de l’utilisateur.
Comprendre comment utiliser les sélecteurs de fichiers

Le sélecteur de fichiers sert généralement à accéder aux fichiers et aux dossiers du Groupement résidentiel. Pour savoir comment utiliser le sélecteur de fichiers dans Démarrage rapide : accès aux fichiers à l’aide de sélecteurs de fichiers.
Comprendre les requêtes de fichiers et de dossiers

Vous pouvez utiliser des requêtes pour énumérer les fichiers et les dossiers du Groupement résidentiel. Pour en savoir plus sur les requêtes de fichiers et de dossiers, voir Démarrage rapide : accès aux fichiers par programmation.

Ouvrir le sélecteur de fichiers au Groupement résidentiel

Suivez ces étapes pour ouvrir une instance du sélecteur de fichiers qui permet à l’utilisateur de sélectionner des fichiers et des dossiers du Groupement résidentiel :

Créer et personnaliser le sélecteur de fichiers

Utilisez fileOpenPicker pour créer le sélecteur de fichiers, puis définissez le paramètre SuggestedStartLocation du sélecteur à PickerLocationId.homeGroup. Définissez aussi les autres propriétés qui sont pertinentes pour vos utilisateurs et votre application. Pour obtenir des directives susceptibles de vous aider à choisir comment personnaliser le sélecteur de fichiers, voir Recommandations et liste de vérification sur les sélecteurs de fichiers.

Cet exemple crée un sélecteur de fichiers qui s’ouvre au Groupement résidentiel, inclut des fichiers de tous types et affiche les fichiers sous forme d’images miniatures :
```
var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.homeGroup;
picker.fileTypeFilter.replaceAll(["*"]);
picker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```

Montrer le sélecteur de fichiers

Une fois que vous avez créé et personnalisé le sélecteur de fichiers, offrez à l’utilisateur la possibilité de choisir un fichier en appelant fileOpenPicker.pickSingleFileAsync. Permettez-lui également de sélectionner plusieurs fichiers en appelant fileOpenPicker.pickMultipleFilesAsync.

Cet exemple montre comment afficher le sélecteur de fichiers pour permettre à l’utilisateur de sélectionner un seul fichier, et comment capturer ce fichier en vue de son traitement :

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

Chercher des fichiers dans le Groupement résidentiel

Cette sélection illustre comment trouver des éléments du Groupement résidentiel qui correspondent à un terme de requête fourni par l’utilisateur.

Obtenir le terme de requête de l’utilisateur.

Nous obtenons ici un terme de requête que l’utilisateur a entré dans un champ d’entrée :
```
var query = document.getElementById("queryString").value;
```

Définir les options de requête et le filtre de recherche.

Les options de requête déterminent la manière avec laquelle les résultats de la recherche sont triés, tandis que le filtre de recherche détermine quels éléments sont inclus dans les résultats de la recherche.

Cet exemple définit des options de requête qui trient les résultats de recherche par pertinence, puis par date de modification. Le filtre de recherche est le terme de requête que l’utilisateur a entré à l’étape précédente :

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

Exécutez la requête puis traitez les résultats.

L’exemple suivant exécute la requête de recherche et enregistre les noms de tout fichier correspondant sous forme de liste de chaînes.

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

Rechercher dans le Groupement résidentiel les fichiers partagés d’un utilisateur particulier

Cette section vous montre comment trouver les fichiers du Groupement résidentiel qui sont partagés par un utilisateur particulier.

Obtenir un ensemble d’utilisateurs du Groupement résidentiel.

Chacun des dossiers de premier niveau du Groupement résidentiel représente un utilisateur individuel. Ainsi, pour obtenir la collection d’utilisateurs du Groupement résidentiel, appelez GetFoldersAsync pour récupérer les dossiers du Groupement résidentiel du niveau supérieur, puis répétez l’opération sur les dossiers récupérés pour obtenir les utilisateurs individuels.
```
var hg = Windows.Storage.KnownFolders.homeGroup;
hg.getFoldersAsync().then(function (users) {
    users.forEach(function (user) {

    // TODO: Do something with the user name. 

    });
}
```
Créer une requête de fichier dont la portée correspond à un utilisateur particulier.

L’exemple suivant définit des options de requête pour trier les résultats de la recherche par pertinence, puis par date de modification. Les options de requête sont ensuite appliquées à une requête de recherche dont la portée correspond à un utilisateur particulier.
```
var options = new Windows.Storage.Search.QueryOptions(
    Windows.Storage.Search.CommonFileQuery.orderBySearchRank, ["*"]);
var query = user.createFileQueryWithOptions(options);
```

Exécuter la requête et traiter les fichiers qui en résultent.

Cet exemple exécute la requête de recherche et enregistre les noms des fichiers correspondant à l’utilisateur particulier, sous forme de liste de chaînes.

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

Lecture en continu de la vidéo du Groupement résidentiel

Suivez les étapes suivantes pour lire en continu le contenu vidéo du Groupement résidentiel :

Incluez un élément vidéo dans une page HTML d’application.

L’élément video spécifie le contenu vidéo à lire dans votre application.

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

Ouvrez un sélecteur de fichiers dans le Groupement résidentiel et appliquez un filtre qui inclut les fichiers vidéo dans les formats pris en charge par votre application.

Cet exemple inclut les fichiers .mp4 et .wmv dans le sélecteur d’ouverture de fichier.

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

Convertissez la sélection de fichiers de l’utilisateur en URL, puis définissez l’URL comme source de l’élément vidéo.

L’exemple suivant permet de récupérer l’élément vidéo et l’initialise de sorte qu’il soit invisible et en état de pause. Lorsque l’utilisateur a choisi un fichier vidéo, l’exemple récupère l’URL du fichier, le définit comme source de l’élément video, montre l’élément vidéo et commence à lire la vidéo.

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