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 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 acceder a archivos 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 con 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 los documentos de todos los proveedores que cumplen 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 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 COLUMN_ROOT_ID único y 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 y 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 IDs de los documentos son únicos y no cambian 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_DELETE y FLAG_SUPPORTS_THUMBNAIL. El mismo COLUMN_DOCUMENT_ID se puede incluir 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 lo desees, siempre y cuando puedas acceder a ellos utilizando 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, para leerlos, editarlos, crearlos o borrarlos.
  • La interacción comienza cuando una aplicación, en este ejemplo, una app de fotos, envía el intent ACTION_OPEN_DOCUMENT o ACTION_CREATE_DOCUMENT. El intent puede incluir filtros para definir mejor los criterios, como "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, 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 desde un selector abierto en una búsqueda de imágenes. El selector también muestra todas las raíces disponibles para la app cliente.

Selección de carpetas en el selector del sistema.
Figura 3: Selector que muestra la carpeta Descargas seleccionada como 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. Ahora el usuario puede interactuar con las 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. Luego, el usuario selecciona una sola app desde la que se puede seleccionar un archivo. La app seleccionada debe proporcionar una interfaz de usuario para que el usuario 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 los archivos que otras apps pusieron a disposición. 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 reemplaza a ACTION_GET_CONTENT. La que uses dependerá de las necesidades de tu app:

  • Usa ACTION_GET_CONTENT si quieres que tu app lea o importe datos. Con este enfoque, la app importa una copia de los datos, como un archivo de imagen.
  • Usa ACTION_OPEN_DOCUMENT si quieres que tu app tenga acceso persistente y a largo plazo a documentos de un proveedor. Un ejemplo es una app de edición de fotos que les permite 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 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

Videos

Anterior
Cómo crear un proveedor de contenido
Siguiente
Cómo crear un proveedor de documentos personalizado