O Android 4.4 (API de nível 19) introduz o Framework de acesso ao armazenamento (SAF, na sigla em inglês). Com o SAF, os usuários podem procurar e abrir documentos, imagens e outros arquivos em todos os provedores de armazenamento de documentos preferidos. Uma IU padrão e fácil de usar permite que os usuários procurem e acessem arquivos 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 de acesso a documentos de um provedor podem se integrar com o SAF com 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 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. - App cliente:um app personalizado que invoca as ações da intent
ACTION_CREATE_DOCUMENT,ACTION_OPEN_DOCUMENTeACTION_OPEN_DOCUMENT_TREEe recebe os arquivos retornados pelos provedores de documentos. - Seletor:uma interface do sistema que permite aos usuários acessar documentos de todos os provedores que atendem aos 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.
- Permite que o aplicativo tenha acesso persistente e de longo prazo a documentos de propriedade de um provedor de documentos. Por meio desse acesso, os usuários podem adicionar, editar, salvar e excluir arquivos no provedor.
- Oferece suporte a várias contas de usuário e raízes transitórias, como provedores de armazenamento USB, que só aparecem se o drive está 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 informa uma ou mais
raízes, que são pontos de partida para explorar uma árvore de documentos.
Cada raiz tem um
COLUMN_ROOT_IDexclusivo e aponta para um documento (um diretório) que representa o conteúdo sob essa raiz. As raízes são dinâmicas por design para oferecer suporte a casos de uso como várias contas, dispositivos de armazenamento USB temporá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 exclusivos e não mudam depois de emitidos, já que 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 documentos extras, com o
tipo MIME
MIME_TYPE_DIR. - Cada documento pode ter diferentes funcionalidades, conforme descrito por
COLUMN_FLAGS. Por exemplo,FLAG_SUPPORTS_WRITE,FLAG_SUPPORTS_DELETEeFLAG_SUPPORTS_THUMBNAIL. O mesmoCOLUMN_DOCUMENT_IDpode ser incluído em vários diretórios.
Fluxo de controle
O modelo de dados do provedor de documentos é baseado em uma hierarquia de arquivos tradicional. No entanto, é possível armazenar fisicamente os dados como quiser, desde que
seja possível acessá-los usando a API
DocumentsProvider. Por exemplo, é possível usar armazenamento em nuvem baseado em tags 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. O cliente solicita permissão para interagir com arquivos, o que significa 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_DOCUMENTouACTION_CREATE_DOCUMENT. A intent pode incluir filtros para refinar ainda mais os critérios. Por exemplo, "quero todos os arquivos que podem ser abertos e que tenham o tipo MIME 'imagem'". - 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 oferece aos usuários uma interface padrão para acessar documentos, mesmo quando os provedores de documentos subjacentes são 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 por 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.
Criar 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 em que a pessoa possa procurar e escolher entre os arquivos disponíveis.
No Android 4.4 (nível 19 da API) e versões mais recentes, você tem a opção adicional de usar a intent
ACTION_OPEN_DOCUMENT,
que exibe uma interface do seletor controlada pelo sistema que permite ao usuário
navegar por 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 o ACTION_GET_CONTENT.
A que você vai usar depende das necessidades do seu app:
- Use
ACTION_GET_CONTENTse 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_DOCUMENTse quiser que o app tenha acesso permanente 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 saber mais sobre como oferecer suporte à navegação de arquivos e diretórios usando a interface 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:
Exemplos
- StorageProvider (link em inglês)
Vídeos
- DevBytes: Framework de acesso ao armazenamento para o Android 4.4 (provedor)
- Arquivos virtuais no Framework de acesso ao armazenamento