Ouvrir des fichiers à l'aide de Storage Access Framework

Android 4.4 (niveau d'API 19) introduit le framework d'accès au stockage (SAF, Storage Access Framework). SAF permet aux utilisateurs de parcourir et d'ouvrir des documents, des images et d'autres fichiers sur tous leurs fournisseurs de stockage de documents préférés. Une interface utilisateur standard facile à utiliser permet aux utilisateurs de parcourir les fichiers et d'accéder aux fichiers récents de manière cohérente entre les applications et les fournisseurs.

Les services de stockage cloud ou locaux peuvent participer à cet écosystème en implémentant un DocumentsProvider qui encapsule leurs services. Les applications clientes qui ont besoin d'accéder aux documents d'un fournisseur peuvent s'intégrer à SAF avec quelques lignes de code.

Le SAF comprend les éléments suivants:

• Fournisseur de documents:fournisseur de contenu qui permet à un service de stockage tel que Google Drive d'afficher les fichiers qu'il gère. Un fournisseur de documents est implémenté en tant que sous-classe de la classe DocumentsProvider. Le schéma du fournisseur de documents est basé sur une hiérarchie de fichiers traditionnelle. Toutefois, vous êtes libre de choisir la manière dont votre fournisseur de documents stocke physiquement les données. La plate-forme Android inclut plusieurs fournisseurs de documents intégrés, tels que les téléchargements, les images et les vidéos.
• Application cliente:application personnalisée qui appelle les actions d'intent ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT et ACTION_OPEN_DOCUMENT_TREE, et qui reçoit les fichiers renvoyés par les fournisseurs de documents.
• Sélecteur:UI système qui permet aux utilisateurs d'accéder aux documents de tous les fournisseurs de documents qui répondent aux critères de recherche de l'application cliente.

SAF offre les fonctionnalités suivantes:

• Permet aux utilisateurs de parcourir le contenu de tous les fournisseurs de documents, et pas seulement d'une seule application.
• Permet à votre application de disposer d'un accès persistant à long terme aux documents appartenant à un fournisseur de documents. Grâce à cet accès, les utilisateurs peuvent ajouter, modifier, enregistrer et supprimer des fichiers chez le fournisseur.
• Prise en charge de plusieurs comptes utilisateur et de racines temporaires, telles que des fournisseurs de stockage USB, qui n'apparaissent que si le lecteur est branché.

Présentation

La SAF s'articule autour d'un fournisseur de contenu qui est une sous-classe de la classe DocumentsProvider. Dans un fournisseur de documents, les données sont structurées selon une hiérarchie de fichiers traditionnelle:

Figure 1 : Modèle de données du fournisseur de documents. Une racine pointe vers un seul document, qui lance ensuite la distribution ramifiée de l'arborescence.

Remarques :

• Chaque fournisseur de documents indique une ou plusieurs racines, qui sont des points de départ de l'exploration d'une arborescence de documents. Chaque racine possède un COLUMN_ROOT_ID unique et pointe vers un document (un répertoire) représentant le contenu sous cette racine. Les racines sont conçues de manière dynamique pour prendre en charge des cas d'utilisation tels que l'utilisation de plusieurs comptes, les périphériques de stockage USB temporaires, ou les connexions et déconnexions d'utilisateurs.
• Sous chaque racine se trouve un document unique. Ce document pointe vers 1 à N documents, chacun d'eux pouvant à son tour désigner 1 à N documents.
• Chaque backend de stockage affiche des fichiers et des répertoires individuels en les référençant avec un élément COLUMN_DOCUMENT_ID unique. Les ID de document sont uniques et ne changent pas une fois émis, car ils sont utilisés pour les attributions d'URI persistantes lors des redémarrages de l'appareil.
• Il peut s'agir d'un fichier ouvert, avec un type MIME spécifique, ou d'un répertoire contenant des documents supplémentaires, avec le type MIME MIME_TYPE_DIR.
• Chaque document peut avoir des fonctionnalités différentes, comme décrit par COLUMN_FLAGS. Exemples : FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE et FLAG_SUPPORTS_THUMBNAIL. Le même COLUMN_DOCUMENT_ID peut être inclus dans plusieurs répertoires.

Flux de contrôle

Le modèle de données du fournisseur de documents est basé sur une hiérarchie de fichiers traditionnelle. Cependant, vous pouvez stocker physiquement vos données comme vous le souhaitez, à condition d'y accéder à l'aide de l'API DocumentsProvider. Par exemple, vous pouvez utiliser un stockage cloud basé sur des tags pour vos données.

La figure 2 montre comment une application photo peut utiliser SAF pour accéder aux données stockées:

Figure 2. Flux du framework d'accès au stockage.

Remarques :

• Dans la SAF, les fournisseurs et les clients n'interagissent pas directement. Un client demande l'autorisation d'interagir avec les fichiers, c'est-à-dire de lire, modifier, créer ou supprimer des fichiers.
• L'interaction commence lorsqu'une application (dans cet exemple, une application photo) déclenche l'intent ACTION_OPEN_DOCUMENT ou ACTION_CREATE_DOCUMENT. L'intent peut inclure des filtres pour affiner davantage les critères, tels que "donne-moi tous les fichiers pouvant être ouverts qui possèdent le type MIME 'image'".
• Une fois l'intent déclenché, le sélecteur système accède à chaque fournisseur enregistré et affiche à l'utilisateur les racines du contenu correspondant.
• Le sélecteur offre aux utilisateurs une interface standard pour accéder aux documents, même lorsque les fournisseurs de documents sous-jacents sont très différents. Par exemple, la figure 2 montre un fournisseur Google Drive, un fournisseur USB et un fournisseur cloud.

Dans la figure 3, l'utilisateur sélectionne le dossier "Downloads" (Téléchargements) dans un sélecteur ouvert lors d'une recherche d'images. Le sélecteur affiche également toutes les racines disponibles pour l'application cliente.

Figure 3. Outil de sélection affichant le dossier "Downloads" (Téléchargements) comme emplacement de recherche

Une fois que l'utilisateur a sélectionné le dossier "Téléchargements", les images s'affichent. La figure 4 illustre le résultat de ce processus. L'utilisateur peut désormais interagir avec les images de la manière prise en charge par le fournisseur et l'application cliente.

Figure 4. Images stockées dans le dossier "Downloads" (Téléchargements), tel qu'affiché dans le sélecteur système

Écrire une application cliente

Sur Android 4.3 et versions antérieures, si vous souhaitez que votre application récupère un fichier d'une autre application, elle doit appeler un intent tel que ACTION_PICK ou ACTION_GET_CONTENT. L'utilisateur sélectionne ensuite une seule application dans laquelle choisir un fichier. L'application sélectionnée doit fournir une interface utilisateur qui permet à l'utilisateur de parcourir les fichiers disponibles et de les sélectionner.

Sur Android 4.4 (niveau d'API 19) ou version ultérieure, vous avez la possibilité supplémentaire d'utiliser l'intent ACTION_OPEN_DOCUMENT, qui affiche une interface utilisateur de sélection contrôlée par le système qui permet à l'utilisateur de parcourir tous les fichiers mis à disposition par d'autres applications. À partir de cette interface utilisateur unique, l'utilisateur peut choisir un fichier dans n'importe quelle application compatible.

Sur Android 5.0 (niveau d'API 21) ou version ultérieure, vous pouvez également utiliser l'intent ACTION_OPEN_DOCUMENT_TREE, qui permet à l'utilisateur de choisir un répertoire auquel une application cliente peut accéder.

Pour en savoir plus sur la prise en charge de la navigation dans les fichiers et les répertoires à l'aide de l'interface utilisateur du sélecteur système, consultez le guide sur l'accès aux documents et aux autres fichiers.

Ressources supplémentaires

Pour en savoir plus sur les fournisseurs de documents, consultez les ressources suivantes:

Exemples

• StorageProvider

Vidéos

• DevBytes: Android 4.4 Storage Access Framework: Provider
• Fichiers virtuels dans le framework d'accès au stockage