Démarrage rapide : accès aux fichiers à l’aide de sélecteurs de fichiers (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 aux fichiers et dossiers via le sélecteur de fichiers en permettant aux utilisateurs de choisir des fichiers et des dossiers. Vous pouvez utiliser la classe fileOpenPicker pour accéder aux fichiers et folderPicker pour accéder aux dossiers.

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.

interface utilisateur de sélecteur de fichiers

Les sélecteurs de fichiers ont des zones en haut et en bas de l’écran qui affichent des informations. Celles-ci permettent aux utilisateurs de s’orienter et leur fournissent une expérience cohérente quand ils accèdent aux fichiers ou les enregistrent.

Les informations affichées incluent les éléments suivants :

Emplacement actuel, situé en haut à gauche
Panier des articles choisis par l’utilisateur, en bas
Liste déroulante des emplacements que l’utilisateur peut parcourir (liste pouvant être sélectionnée à partir du symbole d’accent circonflexe à l’envers, situé en haut à gauche)

Par exemple, cette capture d’écran montre un sélecteur de fichiers qui a été appelé pour permettre à l’utilisateur de sélectionner des photos. Dans la capture d’écran, l’utilisateur a sélectionné deux fichiers. Capture d’écran d’un sélecteur de fichiers dans lequel deux fichiers sont sélectionnés pour ouverture.

L’utilisateur peut voir la liste déroulante des emplacements disponibles (par exemple la liste affichée dans la capture d’écran sur la droite) en sélectionnant le symbole d’accent circonflexe vers le bas situé en haut à gauche du sélecteur de fichiers. Ces emplacements incluent ceux du système de fichiers, comme le dossier Musique ou Téléchargements. Ils incluent également d’autres applications, si celles-ci (comme Microsoft OneDrive) participent à des contrats de sélecteurs de fichiers, que vous pouvez voir au bas de la liste dans la capture d’écran.

Capture d’écran rognée du sélecteur de fichiers affichant en haut à gauche la liste déroulante des emplacements.

Code complet pour sélectionner un fichier

L’exemple du sélecteur de fichiers montre comment utiliser fileOpenPicker pour permettre à l’utilisateur de sélectionner un fichier donné.

// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);

// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

Pour le code complet permettant de sélectionner plusieurs fichiers, voir l’exemple de sélecteur de fichiers.

Procédure pas à pas pour sélectionner un fichier

L’appel du sélecteur de fichiers nécessite deux tâches de base : la création et la personnalisation d’un objet sélecteur de fichiers, et l’affichage du sélecteur de fichiers pour que l’utilisateur puisse sélectionner un ou plusieurs éléments.

Créer et personnaliser un FileOpenPicker

Utilisez fileOpenPicker si l’utilisateur sélectionne un ou plusieurs fichiers. Vous pouvez personnaliser cette classe en définissant des propriétés sur l’objet que vous créez.

L’exemple du sélecteur de fichiers montre comment créer et personnaliser un objet fileOpenPicker.
```
// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
Sur l’objet sélecteur de fichiers, définissez les 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. Pour des explications sur les raisons pour lesquelles nous définissons certaines propriétés pour personnaliser les sélecteurs de fichiers dans l’exemple de sélecteur de fichiers, poursuivez la lecture.

Personnalisations de l’exemple de sélecteur de fichiers FileOpenPicker, explications

L’exemple de sélecteur de fichiers crée un éventail visuel riche d’images dans un emplacement pratique où l’utilisateur peut faire son choix en définissant trois propriétés fileOpenPicker : viewMode, suggestedStartLocation et fileTypeFilter.
- Définir openPicker.viewMode à la valeur enum thumbnail PickerViewMode crée un éventail visuel riche utilisant des images miniatures pour représenter les fichiers dans le sélecteur de fichiers.
```
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
  Envisagez de définir viewMode à PickerViewMode.thumbnail si vous utilisez le sélecteur de fichiers pour afficher des fichiers visuels comme des images ou des vidéos. Autrement, utilisez PickerViewMode.list.
  
  Dans certains cas, l’utilisateur peut souhaiter sélectionner une image ou une vidéo, ou tout autre type de fichier. Par exemple, l’utilisateur peut sélectionner un fichier à joindre à un message électronique ou à envoyer par messagerie instantanée. Dans ce cas, prenez en charge les deux modes d’affichage en ajoutant deux contrôles d’interface utilisateur à votre application. Un contrôle doit appeler le sélecteur de fichiers en utilisant le mode d’affichage thumbnail, de sorte que l’utilisateur puisse sélectionner des images et des vidéos. L’autre contrôle doit appeler le sélecteur de fichiers en utilisant le mode d’affichage list, de sorte que l’utilisateur puisse sélectionner d’autres types de fichiers. Par exemple, une application de messagerie aura deux boutons : Joindre une image ou une vidéo et Joindre un document.
- Définir openPicker.suggestedStartLocation sur Images avec PickerLocationId.picturesLibrary permet à l’utilisateur de démarrer à un emplacement où il est susceptible de trouver des images.
```
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
```
  Définissez suggestedStartLocation sur un emplacement du système de fichiers approprié au type de fichier sélectionné. Si l’utilisateur sélectionne de la musique, des images ou des vidéos, définissez respectivement l’emplacement de départ sur Musique, Images ou Vidéos. Pour tous les autres types de fichiers, définissez l’emplacement de départ sur Documents. Il s’agit juste d’un emplacement de départ. Les utilisateurs peuvent naviguer vers d’autres emplacements tant qu’ils utilisent le sélecteur de fichiers.
  
  De plus, le suggestedStartLocation n’est pas toujours utilisé comme emplacement de départ pour le sélecteur de fichiers. Pour donner à l’utilisateur une impression de cohérence, le sélecteur de fichiers se souvient du dernier emplacement que l’utilisateur a consulté et l’utilisera généralement comme emplacement de départ.
- Utiliser openPicker.fileTypeFilter.replaceAll pour spécifier les types des fichiers que l’utilisateur peut voir dans le sélecteur de fichiers nous permet de garder l’utilisateur concentré sur la sélection de fichiers pertinents et utilisables.
```
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
  Vous devez envisager de spécifier les types de fichiers à afficher dans le sélecteur de fichiers pour veiller à ce que les fichiers affichés soient pertinents. Par exemple, si votre application est un lecteur vidéo, vous pouvez utiliser la propriété fileTypeFilter pour veiller à ce que les fichiers affichés dans le sélecteur de fichiers soient dans des formats vidéo pris en charge par votre lecteur, d’après leurs extensions de nom de fichier.
  
  Si vous souhaitez remplacer d’anciens types de fichiers dans fileTypeFilter par de nouvelles entrées, vous pouvez utiliser la méthode append à la place de la méthode replaceAll.
Montrer le FileOpenPicker

Vous pouvez maintenant montrer le sélecteur de fichiers pour que l’utilisateur puisse sélectionner un ou plusieurs fichiers :
- Montrer pour que l’utilisateur puisse sélectionner un fichier
  
  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. Quand l’utilisateur sélectionne un fichier, fileOpenPicker.pickSingleFileAsync renvoie un objet storageFile qui représente le fichier sélectionné.
  
  L’exemple du sélecteur de fichiers montre comment afficher le sélecteur pour permettre à l’utilisateur de sélectionner un seul fichier, et comment capturer ce fichier en vue de son traitement.
```
// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  À la fin de l’appel de openPicker.pickSingleFileAsync, le fichier sélectionné (représenté par un objet storageFile) est transmis à un littéral de fonction pour être traité en tant que paramètre file. Si l’opération a été annulée et que rien n’a été sélectionné, ce paramètre sera null.
- Montrer pour que l’utilisateur puisse sélectionner plusieurs fichiers
  
  Une fois que vous avez créé et personnalisé un sélecteur de fichiers, offrez la possibilité à l’utilisateur de choisir plusieurs fichiers en appelant fileOpenPicker.pickMultipleFilesAsync.
  
  Si l’utilisateur sélectionne plusieurs fichiers, fileOpenPicker.pickMultipleFilesAsync renvoie la liste des objets storageFile qui représentent les fichiers sélectionnés.
  
  L’exemple du sélecteur de fichiers montre comment afficher le sélecteur pour permettre à l’utilisateur de sélectionner plusieurs fichiers, et comment capturer la liste des fichiers sélectionnés en vue de leur traitement.
```
openPicker.pickMultipleFilesAsync().then(function (files) {
    if (files.size > 0) {
        // Application now has read/write access to the picked file(s)
        var outputString = "Picked files:\n";
        for (var i = 0; i < files.size; i++) {
            outputString = outputString + files[i].name + "\n";
        }
        WinJS.log && WinJS.log(outputString, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  À la fin de l’appel de openPicker.pickMultipleFilesAsync, la liste des fichiers sélectionnés (représentés par des objets ) est transmise à un littéral de fonction pour être traitée en tant que paramètre files. Les fichiers de la liste sont représentés par des objets storageFile. Si l’opération a été annulée et que rien n’a été sélectionné, ce paramètre aura une taille supérieure à 0.

Code complet pour sélectionner un dossier

L’exemple du sélecteur de fichiers montre comment utiliser folderPicker pour permettre à l’utilisateur de sélectionner un dossier.

// Verify that we are currently not snapped, or that we can unsnap to open the picker
var currentState = Windows.UI.ViewManagement.ApplicationView.value;
if (currentState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
    !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
    // Fail silently if we can't unsnap
    return;
}

// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);

folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

Procédure pas à pas pour sélectionner un dossier

Créer et personnaliser un FolderPicker

Utilisez folderPicker si l’utilisateur sélectionne un dossier. Vous pouvez personnaliser cette classe en définissant des propriétés sur l’objet que vous créez.

L’exemple du sélecteur de fichiers montre comment créer et personnaliser un objet folderPicker.
```
// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
Sur l’objet sélecteur de fichiers, définissez les 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. Pour des explications sur les raisons pour lesquelles nous définissons certaines propriétés pour personnaliser les sélecteurs de fichiers dans l’exemple de sélecteur de fichiers, poursuivez la lecture.

Personnalisations de l’exemple de sélecteur de fichiers FolderPicker, explications

L’exemple de sélecteur de fichiers personnalise un sélecteur de fichiers en sélecteur de dossiers à l’aide de trois propriétés folderPicker : viewMode, suggestedStartLocation et fileTypeFilter.
- Utiliser l’objet PickerViewMode.list par défaut pour folderPicker.viewMode nous permet de créer un affichage en forme de liste dans le sélecteur. Cette liste est parfaite pour sélectionner les fichiers qui ne sont pas très visuels, comme les documents.
  
  Envisagez de définir viewMode à PickerViewMode.thumbnail si vous utilisez le sélecteur de fichiers pour afficher des fichiers visuels comme des images ou des vidéos. Autrement, utilisez PickerViewMode.list.
  
  Si vous affichez des fichiers visuels comme des images ou des vidéos, définissez folderPicker.viewMode à thumbnail comme ceci :
```
folderPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
- Définir folderPicker.suggestedStartLocation au bureau de l’utilisateur avec PickerLocationId.desktop permet à l’utilisateur de démarrer à un emplacement familier et fréquemment utilisé.
```
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
```
  Définissez suggestedStartLocation à un emplacement du système de fichiers qui soit approprié pour le type de dossier que l’utilisateur souhaite sélectionner. Par exemple, si l’utilisateur sélectionne un dossier contenant des fichiers musicaux, faites en sorte qu’il démarre dans Musique. Il s’agit juste de l’emplacement de départ. Les utilisateurs peuvent naviguer vers d’autres emplacements tant qu’ils utilisent le sélecteur de fichiers.
  
  De plus, le suggestedStartLocation n’est pas toujours utilisé comme emplacement de départ pour le sélecteur de fichiers. Pour donner à l’utilisateur une impression de cohérence, le sélecteur de fichiers se souvient du dernier emplacement que l’utilisateur a consulté et l’utilisera généralement comme emplacement de départ.
- Utiliser folderPicker.fileTypeFilter.replaceAll pour spécifier les types des fichiers que l’utilisateur peut voir dans le sélecteur de fichiers nous permet de veiller à ce que l’utilisateur reste concentré sur la sélection d’un dossier pertinent.
```
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  Un folderPicker permet aux utilisateurs de sélectionner des dossiers, pas des fichiers individuels. Toutefois, montrer des fichiers pertinents dans le folderPicker aide les utilisateurs à choisir leur dossier. Par exemple, lorsque vous utilisez le folderPicker pour sélectionner un emplacement d’où importer des images, montrer les fichiers d’image aide l’utilisateur à identifier les éléments qui seront importés lorsque l’emplacement sera sélectionné.
Montrer le FolderPicker pour que l’utilisateur puisse sélectionner un dossier

Une fois que vous avez créé et personnalisé un folderPicker, offrez à l’utilisateur la possibilité de choisir un dossier en appelant folderPicker.pickSingleFolderAsync. Quand l’utilisateur sélectionne un fichier, folderPicker.pickSingleFolderAsync renvoie un objet storageFolder qui représente le dossier sélectionné. Il est conseillé de capturer et de traiter ce dossier avec done pour que les exceptions se propagent correctement.

L’exemple du sélecteur de fichiers montre comment afficher le sélecteur pour permettre à l’utilisateur de sélectionner un dossier, et comment capturer ce dossier en vue de son traitement.
```
folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
À la fin de l’appel de folderPicker.pickSingleFolderAsync, le dossier sélectionné est transmis à un littéral de fonction pour être traité en tant que paramètre folder. Le dossier sélectionné est représenté par un objet storageFolder. Si l’opération a été annulée et que rien n’a été sélectionné, ce paramètre sera null.

Récapitulatif et étapes suivantes

Si votre code ressemble à ce qui est montré ici, votre application ouvre un sélecteur de fichiers qui permet aux utilisateurs de sélectionner un ou plusieurs fichiers ou dossiers que votre application peut ensuite ouvrir.

Astuce Chaque fois que votre application accède à un fichier ou un dossier via le sélecteur de fichiers, ajoutez cet élément à la futureAccessList ou à la mostRecentlyUsedList de votre application pour en garder la trace. Pour plus d’informations sur l’utilisation de ces listes, voir Comment suivre les fichiers et les dossiers récemment utilisés.

Pour en savoir plus sur la lecture et l’écriture des fichiers, voir Démarrage rapide : lecture et écriture d’un fichier et l’exemple d’accès au fichier. Pour en savoir plus sur l’utilisation des fichiers d’images, voir Comment sélectionner et afficher une image, Comment décoder une image et l’exemple d’utilisation d’un blob pour enregistrer et charger du contenu.

Pour apprendre à appeler le sélecteur de fichiers afin d’enregistrer des fichiers, voir Comment enregistrer des fichiers via les sélecteurs de fichiers.

Pour que votre application indique des fichiers, un emplacement d’enregistrement ou des mises à jour de fichiers aux autres applications, voir Démarrage rapide : intégration aux contrats du sélecteur de fichiers.