Ouvrir des fichiers à l'aide de Storage Access Framework
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
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".
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.
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.
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:
Le contenu et les exemples de code de cette page sont soumis aux licences décrites dans la Licence de contenu. Java et OpenJDK sont des marques ou des marques déposées d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/07/27 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Il n'y a pas l'information dont j'ai besoin","missingTheInformationINeed","thumb-down"],["Trop compliqué/Trop d'étapes","tooComplicatedTooManySteps","thumb-down"],["Obsolète","outOfDate","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Mauvais exemple/Erreur de code","samplesCodeIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/07/27 (UTC)."],[],[],null,["# Open files using the Storage Access Framework\n\nAndroid 4.4 (API level 19) introduces the Storage Access Framework (SAF). The SAF\nlets users browse and open documents, images, and other files\nacross all of their preferred document storage providers. A standard, easy-to-use UI\nlets users browse files and access recent files in a consistent way across apps and providers.\n\nCloud or local storage services can participate in this ecosystem by implementing a\n[DocumentsProvider](/reference/android/provider/DocumentsProvider) that encapsulates their services. Client\napps that need access to a provider's documents can integrate with the SAF with a few\nlines of code.\n\nThe SAF includes the following:\n\n- **Document provider:** a content provider that lets a storage service, such as Google Drive, reveal the files it manages. A document provider is implemented as a subclass of the [DocumentsProvider](/reference/android/provider/DocumentsProvider) class. The document-provider schema is based on a traditional file hierarchy, though how your document provider physically stores data is up to you. The Android platform includes several built-in document providers, such as Downloads, Images, and Videos.\n- **Client app:** a custom app that invokes the [ACTION_CREATE_DOCUMENT](/reference/android/content/Intent#ACTION_CREATE_DOCUMENT), [ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT), and [ACTION_OPEN_DOCUMENT_TREE](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE) intent actions and receives the files returned by document providers.\n- **Picker:** a system UI that lets users access documents from all document providers that satisfy the client app's search criteria.\n\nSAF offers the following features:\n\n- Lets users browse content from all document providers, not just a single app.\n- Makes it possible for your app to have long-term, persistent access to documents owned by a document provider. Through this access, users can add, edit, save, and delete files on the provider.\n- Supports multiple user accounts and transient roots such as USB storage providers, which only appear if the drive is plugged in.\n\nOverview\n--------\n\nThe SAF centers around a content provider that is a\nsubclass of the [DocumentsProvider](/reference/android/provider/DocumentsProvider) class. Within a document provider, data is\nstructured as a traditional file hierarchy:\n**Figure 1.** Document provider data model. A root points to a single document, which then starts the fan-out of the tree.\n\nNote the following:\n\n- Each document provider reports one or more *roots* , which are starting points into exploring a tree of documents. Each root has a unique [COLUMN_ROOT_ID](/reference/android/provider/DocumentsContract.Root#COLUMN_ROOT_ID), and it points to a document (a directory) representing the contents under that root. Roots are dynamic by design to support use cases like multiple accounts, transient USB storage devices, or user login and logout.\n- Under each root is a single document. That document points to 1 to *N* documents, each of which in turn can point to 1 to *N* documents.\n- Each storage backend surfaces individual files and directories by referencing them with a unique [COLUMN_DOCUMENT_ID](/reference/android/provider/DocumentsContract.Document#COLUMN_DOCUMENT_ID). Document IDs are unique and don't change once issued, since they are used for persistent URI grants across device reboots.\n- Documents can be either an openable file, with a specific MIME type, or a directory containing additional documents, with the [MIME_TYPE_DIR](/reference/android/provider/DocumentsContract.Document#MIME_TYPE_DIR) MIME type.\n- Each document can have different capabilities, as described by [COLUMN_FLAGS](/reference/android/provider/DocumentsContract.Document#COLUMN_FLAGS). For example, [FLAG_SUPPORTS_WRITE](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_WRITE), [FLAG_SUPPORTS_DELETE](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_DELETE), and [FLAG_SUPPORTS_THUMBNAIL](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL). The same `COLUMN_DOCUMENT_ID` can be included in multiple directories.\n\nControl flow\n------------\n\nThe document provider data model is based on a traditional\nfile hierarchy. However, you can physically store your data however you like, as\nlong as you can access it using the [DocumentsProvider](/reference/android/provider/DocumentsProvider)\nAPI. For example, you can use tag-based cloud storage for your data.\n\nFigure 2 shows how a photo app might use the SAF\nto access stored data:\n**Figure 2.** Storage Access Framework flow.\n\nNote the following:\n\n- In the SAF, providers and clients don't interact directly. A client requests permission to interact with files, meaning to read, edit, create, or delete files.\n- The interaction starts when an application, in this example a photo app, fires the intent [ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT) or [ACTION_CREATE_DOCUMENT](/reference/android/content/Intent#ACTION_CREATE_DOCUMENT). The intent can include filters to further refine the criteria, such as \"give me all openable files that have the 'image' MIME type.\"\n- Once the intent fires, the system picker goes to each registered provider and shows the user the matching content roots.\n- The picker gives users a standard interface for accessing documents, even when the underlying document providers are very different. For example, figure 2 shows a Google Drive provider, a USB provider, and a cloud provider.\n\nIn Figure 3, the user is selecting the Downloads folder from a picker opened in a search for\nimages. The picker also shows all of the roots available to the client app.\n**Figure 3.** Picker showing Downloads folder selected as a search location.\n\nAfter the user selects the Downloads folder, the images are displayed. Figure\n4 shows the result of this process. The user can now interact with the images\nin the ways that the provider and client app support.\n**Figure 4.** Images stored in the Downloads folder, as viewed in the system picker.\n\nWrite a client app\n------------------\n\nOn Android 4.3 and lower, if you want your app to retrieve a file from another\napp, it must invoke an intent such as [ACTION_PICK](/reference/android/content/Intent#ACTION_PICK)\nor [ACTION_GET_CONTENT](/reference/android/content/Intent#ACTION_GET_CONTENT). The user then selects\na single app from which to pick a file. The selected app must provide a user\ninterface for the user to browse and pick from the available files.\n\nOn Android 4.4 (API level 19) and higher, you have the additional option of using the\n[ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT) intent,\nwhich displays a system-controlled picker UI that lets the user\nbrowse all files that other apps have made available. From this single UI, the\nuser can pick a file from any of the supported apps.\n\nOn Android 5.0 (API level 21) and higher, you can also use the\n[ACTION_OPEN_DOCUMENT_TREE](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE)\nintent, which lets the user choose a directory for a client app to\naccess. \n**Note:** `ACTION_OPEN_DOCUMENT` isn't a replacement for `ACTION_GET_CONTENT`.\nThe one you use depends on the needs of your app:\n\n- Use `ACTION_GET_CONTENT` if you want your app to read or import data. With this approach, the app imports a copy of the data, such as an image file.\n- Use `ACTION_OPEN_DOCUMENT` if you want your app to have long-term, persistent access to documents owned by a document provider. An example is a photo-editing app that lets users edit images stored in a document provider.\n\nFor more information about how to support browsing for files and directories\nusing the system picker UI, see the guide about\n[accessing documents and\nother files](/training/data-storage/shared/documents-files).\n\nAdditional resources\n--------------------\n\nFor more information about document providers, take advantage of the\nfollowing resources:\n\n### Samples\n\n- [StorageProvider](https://github.com/android/storage-samples/tree/main/StorageProvider)\n\n### Videos\n\n- [DevBytes: Android 4.4 Storage Access Framework: Provider](http://www.youtube.com/watch?v=zxHVeXbK1P4)\n- [Virtual Files in the Storage Access Framework](https://www.youtube.com/watch?v=4h7yCZt231Y)"]]
