Android 4.4 (nivel de API 19) presenta el framework de acceso al almacenamiento (SAF). El SAF permite a los usuarios examinar y abrir documentos, imágenes y otros archivos en todos sus proveedores de almacenamiento de documentos preferidos. Una IU estándar y fácil de usar les permite explorar archivos y accesos recientes de manera coherente en apps y proveedores.
Los servicios de almacenamiento local o en la nube pueden participar en este ecosistema implementando un DocumentsProvider que encapsule sus servicios. Las apps cliente que necesiten acceso a documentos de un proveedor pueden integrarse con el SAF mediante unas pocas líneas de código.
El SAF incluye lo siguiente:
- Proveedor de documentos: es un proveedor de contenido que permite a un servicio de almacenamiento (como Google Drive) revelar los archivos que administra. Un proveedor de documentos se implementa como una subclase de la clase
DocumentsProvider. El esquema de proveedor de documentos se basa en una jerarquía de archivos tradicional, aunque la forma en que el proveedor de documentos almacena físicamente los datos depende de ti. La plataforma de Android incluye varios proveedores de documentos integrados, como Descargas, Imágenes y Videos. - App cliente: es una app personalizada que invoca las acciones de intent
ACTION_CREATE_DOCUMENT,ACTION_OPEN_DOCUMENTyACTION_OPEN_DOCUMENT_TREE, y recibe los archivos que muestran los proveedores de documentos. - Selector: es una IU del sistema que les permite a los usuarios acceder a los documentos de todos los proveedores que cumplen los criterios de búsqueda de la app cliente.
Algunas de las funciones que ofrece el SAF son las siguientes:
- Permite que los usuarios exploren contenido de todos los proveedores de contenido, no solo de una aplicación individual.
- Permite que tu app tenga acceso persistente y a largo plazo a documentos de un proveedor. Mediante este acceso, los usuarios pueden agregar, editar, guardar y borrar archivos en el proveedor.
- Admite varias cuentas de usuario y raíces transitorias, como proveedores de almacenamiento USB, que solo aparecen si la unidad está conectada.
Descripción general
El SAF se centra en un proveedor de contenido que es una subclase de la clase DocumentsProvider. En un proveedor de documentos, los datos se estructuran como una jerarquía de archivos tradicional de la siguiente manera:
Figura 1: Modelo de datos del proveedor de documentos. Una raíz apunta a un solo documento, que luego se distribuye a todo el árbol.
Ten en cuenta lo siguiente:
- Cada proveedor de documentos informa de una o más "raíces", que son puntos de partida para explorar un árbol de documentos.
Cada raíz tiene un único
COLUMN_ROOT_IDy apunta a un documento (un directorio) que representa el contenido que incluye esa raíz. Las raíces tienen un diseño dinámico que admite casos de uso como cuentas múltiples, dispositivos de almacenamiento USB transitorios o accesos o salidas de la cuenta por parte de usuarios. - En cada raíz, hay un solo documento. Ese documento hace referencia de 1 a N documentos, cada uno de los cuales a la vez puede hacer referencia de 1 a N documentos.
- Cada backend de almacenamiento presenta archivos y directorios individuales haciendo referencia a ellos con un único
COLUMN_DOCUMENT_ID. Los ID de los documentos deben ser únicos y no deben cambiar una vez que se emiten, ya que se usan para asignar URI persistentes en los reinicios del dispositivo. - Los documentos pueden ser un archivo que se abra (con un tipo de MIME específico) o un directorio que contenga documentos adicionales (con el tipo de MIME
MIME_TYPE_DIR). - Cada documento puede tener diferentes capacidades, como se describe en
COLUMN_FLAGS. Por ejemplo:FLAG_SUPPORTS_WRITE,FLAG_SUPPORTS_DELETEyFLAG_SUPPORTS_THUMBNAIL. El mismoCOLUMN_DOCUMENT_IDpuede incluirse en varios directorios.
Flujo de control
Como se indicó anteriormente, el modelo de datos del proveedor de documentos se basa en una jerarquía de archivos tradicional. Sin embargo, puedes almacenar físicamente tus datos como lo desees, siempre y cuando puedas acceder a ellos utilizando la API de DocumentsProvider. Por ejemplo, podrías usar almacenamiento en la nube basado en etiquetas para tus datos.
La figura 2 muestra un ejemplo de cómo una app de fotos podría usar el SAF para acceder a datos almacenados:
Figura 2: Flujo del framework de acceso a almacenamiento
Ten en cuenta lo siguiente:
- En el SAF, los proveedores y los clientes no interactúan directamente. Un cliente solicita permiso para interactuar con archivos (es decir, para leerlos, editarlo, crearlo o borrarlos).
- La interacción comienza cuando una app (en este ejemplo, una de fotos) envía el intent
ACTION_OPEN_DOCUMENToACTION_CREATE_DOCUMENT. El intent puede incluir filtros para refinar aún más los criterios; por ejemplo, "mostrar todos los archivos que se puedan abrir y que tengan el tipo de MIME 'imagen'". - Una vez que se envía el intent, el selector del sistema se dirige a cada proveedor registrado y le muestra al usuario las raíces de contenido coincidentes.
- El selector les proporciona a los usuarios una interfaz estándar para acceder a documentos, aunque los proveedores de documentos subyacentes sean muy diferentes. Por ejemplo, la figura 2 muestra un proveedor de Google Drive, un proveedor de USB y un proveedor de servicios en la nube.
La figura 3 muestra un selector en el que un usuario que busca imágenes seleccionó la carpeta Descargas. También muestra todas las raíces disponibles para la app cliente.
Figura 3: Selector
Una vez que el usuario selecciona la carpeta Descargas, se muestran las imágenes. En la figura 4, se muestra el resultado de este proceso. Ahora el usuario puede interactuar con estas imágenes de las formas que admitan el proveedor y la app cliente.
Figura 4: Imágenes almacenadas en la carpeta Descargas, tal como se ven en el selector del sistema
Cómo escribir una app cliente
En Android 4.3 y versiones anteriores, si quieres que tu app muestre un archivo de otra app, debe invocar un intent como ACTION_PICK o ACTION_GET_CONTENT. El usuario debe seleccionar una sola app desde la que se pueda seleccionar un archivo, y la app seleccionada debe proporcionar una interfaz de usuario para que este explore y seleccione entre los archivos disponibles.
En Android 4.4 (nivel de API 19) y versiones posteriores, tienes la opción adicional de usar el intent ACTION_OPEN_DOCUMENT, que muestra una IU de selector controlada por el sistema que le permite al usuario explorar todos archivos disponibles de otras apps. Desde esta IU individual, el usuario puede seleccionar un archivo de cualquiera de las apps compatibles.
En Android 5.0 (nivel de API 21) y versiones posteriores, también puedes usar el intent ACTION_OPEN_DOCUMENT_TREE, que permite al usuario elegir un directorio para acceder a una app cliente.
Nota: ACTION_OPEN_DOCUMENT no está pensado para reemplazar ACTION_GET_CONTENT. El que debes usar depende de las necesidades de tu app, como se indica a continuación:
- Usa
ACTION_GET_CONTENTsi quieres que tu app solo lea o importe datos. Con este enfoque, la app importa una copia de los datos, como un archivo de imagen. - Usa
ACTION_OPEN_DOCUMENTsi quieres que tu app tenga acceso persistente y a largo plazo a documentos de un proveedor. Un ejemplo sería una app de edición de fotos que les permitiera a los usuarios editar imágenes almacenadas en un proveedor de documentos.
Para obtener más información sobre cómo agregar compatibilidad con el acceso a archivos y directorios mediante la IU del selector del sistema, consulta la guía para acceder a documentos y otros archivos.
Recursos adicionales
Para obtener más información sobre los proveedores de documentos, consulta los siguientes recursos: