Ouvrir des fichiers à l'aide de Storage Access Framework

Android 4.4 (niveau d'API 19) introduit Storage Access Framework (SAF). Le 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 et 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 au SAF avec quelques lignes de code.

Le SAF inclut les éléments suivants:

  • Fournisseur de documents:fournisseur de contenu qui permet à un service de stockage, tel que Google Drive, de révéler 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, mais la manière dont votre fournisseur de documents stocke physiquement les données dépend de vous. La plate-forme Android inclut plusieurs fournisseurs de documents intégrés, tels que "Téléchargements", "Images" et "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 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 propose 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 d'avoir un accès persistant et à long terme aux documents appartenant à un fournisseur de documents. Grâce à cet accès, les utilisateurs peuvent ajouter, modifier, enregistrer et supprimer des fichiers sur le fournisseur.
  • Compatible avec plusieurs comptes utilisateur et racines temporaires telles que les fournisseurs de stockage USB, qui n'apparaissent que si le disque est branché.

Présentation

Le 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 comme une hiérarchie de fichiers classique:

Figure 1. Modèle de données du fournisseur de documents. Une racine pointe vers un seul document, qui lance ensuite le développement de l'arborescence.

Remarques :

  • Chaque fournisseur de documents signale une ou plusieurs racines, qui sont des points de départ pour explorer un arbre 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 dynamiques par conception pour prendre en charge des cas d'utilisation tels que plusieurs comptes, des périphériques de stockage USB temporaires ou la connexion et la déconnexion des utilisateurs.
  • Chaque racine contient un seul document. Ce document pointe vers 1 à N documents, chacun pouvant pointer vers 1 à N documents.
  • Chaque backend de stockage affiche des fichiers et des répertoires individuels en les référençant avec un COLUMN_DOCUMENT_ID unique. Les ID de document sont uniques et ne changent pas une fois émis, car ils sont utilisés pour les autorisations d'URI persistantes lors des redémarrages de l'appareil.
  • Les documents peuvent être un fichier pouvant être ouvert, avec un type MIME spécifique, ou 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. Par exemple, 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. Toutefois, vous pouvez stocker vos données physiquement comme vous le souhaitez, à condition d'y accéder à l'aide de l'API DocumentsProvider. Par exemple, vous pouvez utiliser le stockage cloud basé sur des tags pour vos données.

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

Figure 2. Flux Storage Access Framework.

Remarques :

  • Dans le SAF, les fournisseurs et les clients n'interagissent pas directement. Un client demande l'autorisation d'interagir avec des fichiers, c'est-à-dire de les lire, de les modifier, de les créer ou de les supprimer.
  • 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, par exemple "donnez-moi tous les fichiers ouverts avec 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 de contenu correspondantes.
  • 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 "Téléchargements" à partir d'un sélecteur ouvert lors d'une recherche d'images. Le sélecteur affiche également toutes les racines disponibles pour l'application cliente.

Sélection de dossier dans le sélecteur système.
Figure 3 Sélecteur montrant le dossier "Téléchargements" sélectionné 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 compatible avec le fournisseur et l'application cliente.

Figure 4. Images stockées dans le dossier "Téléchargements", telles qu'elles apparaissent dans le sélecteur système.

Écrire une application cliente

Sous Android 4.3 et versions antérieures, si vous souhaitez que votre application récupère un fichier à partir 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 à partir de laquelle choisir un fichier. L'application sélectionnée doit fournir une interface utilisateur permettant à l'utilisateur de parcourir et de choisir parmi les fichiers disponibles.

Sur Android 4.4 (niveau d'API 19) ou version ultérieure, vous avez la possibilité d'utiliser l'intent ACTION_OPEN_DOCUMENT, qui affiche une UI de sélecteur 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 sélectionner un fichier dans l'une des applications compatibles.

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.

Remarque : ACTION_OPEN_DOCUMENT ne remplace pas ACTION_GET_CONTENT. Le choix de la structure dépend des besoins de votre application:

  • Utilisez ACTION_GET_CONTENT si vous souhaitez que votre application lise ou importe des données. Avec cette approche, l'application importe une copie des données, comme un fichier image.
  • Utilisez ACTION_OPEN_DOCUMENT si vous souhaitez que votre application dispose d'un accès persistant à long terme aux documents appartenant à un fournisseur de documents. Par exemple, une application de retouche photo qui permet aux utilisateurs de modifier des images stockées dans un fournisseur de documents.

Pour en savoir plus sur la prise en charge de la navigation dans les fichiers et les répertoires à l'aide de l'UI 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

Vidéos

Précédent
Créer un fournisseur de contenu
Suivant
Créer un fournisseur de documents personnalisé