Cómo abrir archivos con el framework de acceso al almacenamiento

Android 4.4 (nivel de API 19) presenta el framework de acceso al almacenamiento (SAF). El SAF permite a los usuarios explorar y abrir documentos, imágenes y otros archivos en todos sus proveedores preferidos de almacenamiento de documentos. Una IU estándar y fácil de usar permite a los usuarios explorar archivos y acceder a archivos recientes de manera coherente en todas las apps y los 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 que un servicio de almacenamiento, como Google Drive, revele 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_DOCUMENT y ACTION_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 documentos de todos los proveedores que cumplen con los criterios de búsqueda de la app cliente.

SAF ofrece las siguientes funciones:

• 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 con el árbol.

Ten en cuenta lo siguiente:

• Cada proveedor de documentos informa una o más raíces, que son puntos de partida para explorar un árbol de documentos. Cada raíz tiene un COLUMN_ROOT_ID único y apunta a un documento (un directorio) que representa el contenido que se incluye en ella. Las raíces tienen un diseño dinámico para admitir casos de uso como cuentas múltiples, dispositivos de almacenamiento USB transitorios o accesos y salidas 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 IDs de documento son únicos y no cambian una vez que se emiten, ya que se usan para otorgamientos de URI persistentes en todos los reinicios del dispositivo.
• Los documentos pueden ser un archivo que se pueda abrir, 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_DELETE y FLAG_SUPPORTS_THUMBNAIL. Se puede incluir el mismo COLUMN_DOCUMENT_ID en varios directorios.

Flujo de control

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 quieras, siempre y cuando puedas acceder a ellos con la API de DocumentsProvider. Por ejemplo, puedes 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 al 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, leer, editar, crear o borrar archivos.
• La interacción comienza cuando una aplicación (en este ejemplo, una app de fotos) activa el intent ACTION_OPEN_DOCUMENT o ACTION_CREATE_DOCUMENT. El intent puede incluir filtros para refinar aún más los criterios, como "mostrarme 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, incluso cuando los proveedores de documentos subyacentes son 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.

En la Figura 3, el usuario selecciona la carpeta Descargas en un selector abierto en una búsqueda de imágenes. El selector también muestra todas las raíces disponibles para la app cliente.

Figura 3: El selector muestra la carpeta Descargas seleccionada como una ubicación de búsqueda.

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. El usuario ahora puede interactuar con las imágenes de las formas compatibles con el proveedor y la app cliente.

Figura 4: Imágenes almacenadas en la carpeta Descargas, como se ve en el selector del sistema.

Escribe 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. Luego, el usuario selecciona una sola app para elegir un archivo. La app seleccionada debe proporcionar una interfaz de usuario para que el usuario explore y elija 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 controlado por el sistema que le permite al usuario explorar todos los 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 le permite al usuario elegir un directorio para acceder a una app cliente.

Si quieres obtener más información para admitir la navegación de archivos y directorios con la IU del selector del sistema, consulta la guía sobre cómo acceder a documentos y otros archivos.

Recursos adicionales

Para obtener más información sobre los proveedores de documentos, consulta los siguientes recursos:

Ejemplos

• StorageProvider

Videos

• DevBytes: framework de acceso al almacenamiento de Android 4.4: proveedor
• Archivos virtuales en el framework de acceso al almacenamiento