Abrir arquivos com o Framework de acesso ao armazenamento
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
O Android 4.4 (API de nível 19) introduz o Framework de acesso ao armazenamento (SAF, na sigla em inglês). O SAF
permite que os usuários naveguem e abram documentos, imagens e outros arquivos
em todos os provedores de armazenamento de documentos mais usados. Uma interface padrão fácil de usar
permite que os usuários procurem arquivos e acessem documentos recentes de maneira consistente em todos os apps e provedores.
Os serviços de armazenamento local ou em nuvem podem participar desse ecossistema implementando um
DocumentsProvider que encapsule os serviços. Os apps
clientes que precisam acessar documentos de um provedor podem fazer a integração com o SAF com apenas algumas
linhas de código.
O SAF contém o seguinte:
Provedor de documentos:um provedor de conteúdo que permite que um
serviço de armazenamento, como o Google Drive, revele os arquivos que ele gerencia. Um provedor de documentos é
implementado como subclasse da classe DocumentsProvider.
O esquema do provedor de documentos é baseado em uma hierarquia de arquivos tradicional,
mas depende de você a maneira como seu provedor armazena os dados fisicamente.
A plataforma Android inclui vários provedores de documentos integrados, como
Downloads, Imagens e Vídeos.
Seletor:uma interface do sistema que permite aos usuários acessar documentos de todos
os provedores de documentos que satisfazem os critérios de pesquisa do app cliente.
O SAF oferece os seguintes recursos:
Permite que usuários procurem conteúdo de todos os provedores de documentos, não somente de um único app.
Isso permite que o app tenha acesso persistente e de longo prazo a
documentos de propriedade de um provedor de documentos. Com esse acesso, os usuários podem adicionar, editar,
salvar e excluir arquivos no provedor.
É compatível com várias contas de usuário e raízes transitórias, como provedores de armazenamento USB,
que só aparecem se o drive estiver conectado.
Visão geral
O SAF consiste em um provedor de conteúdo que é uma
subclasse da classe DocumentsProvider. Dentro de um provedor de documentos, os dados são
estruturados como uma hierarquia de arquivo tradicional:
Figura 1. Modelo de dados do provedor de documentos. Uma raiz aponta para um único documento, que inicia a distribuição de dados da árvore.
Observe o seguinte:
Cada provedor de documentos relata uma ou mais
raízes, que são pontos de partida para explorar uma árvore de documentos.
Cada raiz tem um COLUMN_ROOT_ID exclusivo
que aponta para um documento (um diretório)
representando o conteúdo sob essa raiz.
As raízes são naturalmente dinâmicas para oferecer compatibilidade a casos de uso como várias contas,
dispositivos de armazenamento USB transitórios ou login e logout do usuário.
Sob cada raiz há um documento único. Esse documento indica de 1 a N documentos,
e cada um deles pode indicar de 1 a N documentos.
Cada back-end de armazenamento exibe
arquivos e diretórios individuais referenciando-os com um COLUMN_DOCUMENT_ID
único.
Os IDs de documentos são únicos e não mudam depois de emitidos. Isso porque eles são usados para concessões
persistentes do URI em reinicializações do dispositivo.
Os documentos podem ser arquivos que podem ser abertos, com um tipo MIME específico, ou um
diretório contendo outros documentos, com o
tipo MIME MIME_TYPE_DIR.
O modelo de dados do provedor de documentos é baseado em uma hierarquia de
arquivos tradicional. No entanto, você pode armazenar fisicamente seus dados da maneira que quiser, contanto
que possa acessá-los usando a API
DocumentsProvider. Por exemplo, é possível usar armazenamento em nuvem com base em tag para os dados.
A Figura 2 mostra como um app de fotos poderia usar o SAF
para acessar dados armazenados:
Figura 2. Fluxo do framework de acesso ao armazenamento.
Observe o seguinte:
No SAF, provedores e clientes não interagem
diretamente. Um cliente solicita permissão para interagir
com arquivos, ou seja, ler, editar, criar ou excluir arquivos.
A interação começa quando um aplicativo, neste exemplo um app de fotos, dispara a intent
ACTION_OPEN_DOCUMENT ou ACTION_CREATE_DOCUMENT.
A intent pode incluir filtros
para refinar ainda mais os critérios, como "quero todos os arquivos que podem ser abertos
e que têm o tipo MIME 'image'".
Ao disparar a intent, o seletor do sistema contata cada provedor registrado
e exibe para o usuário as raízes de conteúdo correspondentes.
O seletor fornece aos usuários uma interface padrão para acessar documentos, mesmo
que os provedores de documentos subjacentes sejam muito diferentes. Por exemplo, a Figura 2
mostra um provedor do Google Drive, um de USB e outro de nuvem.
Na Figura 3, o usuário está selecionando a pasta Downloads em um seletor aberto em uma pesquisa de
imagens. O seletor também mostra todas as raízes disponíveis para o app cliente.
Figura 3. Seletor mostrando a pasta "Downloads" selecionada como local de pesquisa.
Depois que o usuário seleciona a pasta Downloads, as imagens são exibidas. A Figura
4 mostra o resultado desse processo. Agora o usuário pode interagir com as imagens
de maneiras compatíveis com o provedor e o app cliente.
Figura 4. Imagens armazenadas na pasta "Downloads", conforme visualizado no seletor do sistema.
Programar um app cliente
No Android 4.3 e em versões anteriores, para o app recuperar um arquivo de outro
app, ele precisa chamar uma intent como ACTION_PICK
ou ACTION_GET_CONTENT. Em seguida, o usuário seleciona
um único app para escolher um arquivo. O app selecionado precisa fornecer uma interface
do usuário para que ele navegue e selecione os arquivos disponíveis.
No Android 4.4 (nível 19 da API) e versões mais recentes, também existe a opção de usar a
intent ACTION_OPEN_DOCUMENT,
que exibe uma IU do seletor controlada pelo sistema que permite ao usuário
procurar todos os arquivos disponibilizados por outros apps. Nessa IU exclusiva, o
usuário pode selecionar um arquivo de qualquer app compatível.
No Android 5.0 (nível 21 da API) e versões mais recentes, você também pode usar a
intent ACTION_OPEN_DOCUMENT_TREE, que permite que o usuário escolha um diretório para um app cliente
acessar.
Observação : ACTION_OPEN_DOCUMENT não substitui ACTION_GET_CONTENT.
A escolha depende das necessidades do app:
Use ACTION_GET_CONTENT se quiser que o app
leia ou importe dados. Nessa abordagem, o app importa uma cópia dos dados,
como um arquivo de imagem.
Use ACTION_OPEN_DOCUMENT se quiser que o
app tenha acesso persistente e de longo prazo a documentos de propriedade de um provedor
de documentos. Um exemplo é um app de edição de fotos que permite aos usuários editar
imagens armazenadas em um provedor de documentos.
Para mais informações sobre como oferecer suporte à navegação de arquivos e diretórios
usando a IU do seletor do sistema, consulte o guia sobre
como acessar documentos e
outros arquivos.
Outros recursos
Para ver mais informações sobre provedores de documentos, use os
seguintes recursos:
O conteúdo e os exemplos de código nesta página estão sujeitos às licenças descritas na Licença de conteúdo. Java e OpenJDK são marcas registradas da Oracle e/ou suas afiliadas.
Última atualização 2025-07-27 UTC.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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)"]]
