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
yACTION_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:
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
yFLAG_SUPPORTS_THUMBNAIL
. Se puede incluir el mismoCOLUMN_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:
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
oACTION_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.
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.
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.
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 de documentos. Un ejemplo es una app de edición de fotos que permite a los usuarios editar imágenes almacenadas en un proveedor de documentos.
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
Videos
- DevBytes: framework de acceso al almacenamiento de Android 4.4: proveedor
- Archivos virtuales en el framework de acceso al almacenamiento