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). 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_DOCUMENT e ACTION_OPEN_DOCUMENT_TREE e 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_ID exclusivo 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_DELETE e FLAG_SUPPORTS_THUMBNAIL. O mesmo COLUMN_DOCUMENT_ID pode 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_DOCUMENT ou ACTION_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.

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