Aprire i file utilizzando Storage Access Framework

Android 4.4 (livello API 19) introduce lo Storage Access Framework (SAF). SAF consente agli utenti di sfogliare e aprire documenti, immagini e altri file in tutti i loro fornitori di archiviazione di documenti preferiti. Un'interfaccia utente standard facile da usare consente agli utenti di sfogliare i file e di accedere a quelli recenti in modo coerente tra app e provider.

I servizi di archiviazione cloud o locali possono partecipare a questo ecosistema implementando un DocumentsProvider che incapsula i loro servizi. Le app client che richiedono l'accesso ai documenti di un provider possono integrarsi con SAF con poche righe di codice.

La SAF include quanto segue:

• Fornitore di documenti: un fornitore di contenuti che consente a un servizio di archiviazione, come Google Drive, di rivelare i file che gestisce. Un provider di documenti viene implementato come sottoclasse della classe DocumentsProvider. Lo schema del fornitore di documenti si basa su una gerarchia di file tradizionale, anche se spetta a te decidere il modo in cui il fornitore di documenti archivia fisicamente i dati. La piattaforma Android include diversi fornitori di documenti integrati, tra cui download, immagini e video.
• App client: un'app personalizzata che richiama le azioni di intent ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT e ACTION_OPEN_DOCUMENT_TREE e riceve i file restituiti dai fornitori di documenti.
• Selettore: un'interfaccia utente di sistema che consente agli utenti di accedere ai documenti di tutti i fornitori di documenti che soddisfano i criteri di ricerca dell'app client.

SAF offre le seguenti funzionalità:

• Consente agli utenti di sfogliare i contenuti di tutti i fornitori di documenti, non solo da una singola app.
• Consente alla tua app di avere accesso permanente e a lungo termine ai documenti di proprietà di un fornitore di documenti. Tramite questo accesso, gli utenti possono aggiungere, modificare, salvare ed eliminare i file sul provider.
• Supporta più account utente e root temporanei come provider di archiviazione USB, che vengono visualizzati solo se l'unità è collegata.

Panoramica

SAF è incentrato su un fornitore di contenuti che appartiene a una sottoclasse della classe DocumentsProvider. All'interno di un provider di documenti, i dati sono strutturati come una gerarchia di file tradizionale:

Figura 1. Modello dei dati del fornitore di documenti. La radice rimanda a un singolo documento, da cui viene quindi eseguito il fan-out dell'albero.

Nota:

• Ogni fornitore di documenti segnala una o più root, ovvero i punti di partenza per esplorare una struttura di documenti. Ogni radice ha un COLUMN_ROOT_ID univoco e rimanda a un documento (una directory) che ne rappresenta i contenuti sottostanti. Le istanze root sono progettate in modo dinamico per supportare casi d'uso come account multipli, dispositivi di archiviazione USB temporanei o accesso e disconnessione degli utenti.
• Sotto ogni radice c'è un singolo documento. Tale documento rimanda a da 1 a N documenti, ognuno dei quali a sua volta può indirizzare a da 1 a N documenti.
• Ogni backend di archiviazione visualizza singoli file e directory facendo riferimento a questi file con un COLUMN_DOCUMENT_ID univoco. Gli ID documento sono univoci e non cambiano una volta emessi, poiché vengono utilizzati per concessioni URI permanenti tra i riavvii dei dispositivi.
• I documenti possono essere file apribili, con un tipo MIME specifico, o una directory contenente documenti aggiuntivi, con il tipo MIME MIME_TYPE_DIR.
• Ogni documento può avere funzionalità diverse, come descritto in COLUMN_FLAGS. Ad esempio, FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE e FLAG_SUPPORTS_THUMBNAIL. Lo stesso COLUMN_DOCUMENT_ID può essere incluso in più directory.

Flusso di controllo

Il modello dati del fornitore di documenti si basa su una gerarchia di file tradizionale. Tuttavia, puoi archiviare fisicamente i dati come preferisci, purché tu possa accedervi utilizzando l'API DocumentsProvider. Ad esempio, puoi utilizzare l'archiviazione sul cloud basata su tag per i dati.

La Figura 2 mostra in che modo un'app di foto potrebbe utilizzare SAF per accedere ai dati archiviati:

Figura 2. Flusso di Storage Access Framework.

Nota:

• In SAF, provider e client non interagiscono direttamente. Un client richiede l'autorizzazione per interagire con i file, cioè per leggere, modificare, creare o eliminare i file.
• L'interazione inizia quando un'applicazione, in questo esempio un'app di foto, attiva l'intent ACTION_OPEN_DOCUMENT o ACTION_CREATE_DOCUMENT. L'intent può includere filtri per perfezionare ulteriormente i criteri, ad esempio "fornisci tutti i file apribili che hanno il tipo MIME "image".
• Una volta attivato l'intent, il selettore di sistema viene indirizzato a ciascun fornitore registrato e mostra all'utente le origini dei contenuti corrispondenti.
• Il selettore offre agli utenti un'interfaccia standard per accedere ai documenti, anche quando i fornitori di documenti sottostanti sono molto diversi. Ad esempio, la figura 2 mostra un provider di Google Drive, un provider USB e un cloud provider.

Nella Figura 3 l'utente seleziona la cartella Download da un selettore aperto nella ricerca di immagini. Il selettore mostra anche tutti i certificati radice disponibili per l'app client.

Figura 3. Selettore che mostra la cartella Download selezionata come posizione di ricerca.

Una volta selezionata la cartella Download, l'utente visualizza le immagini. La Figura 4 mostra il risultato di questa procedura. L'utente può ora interagire con le immagini come supportato dal provider e dall'app client.

Figura 4. Immagini memorizzate nella cartella Download, visualizzate nel selettore di sistema.

Scrivi un'app client

Su Android 4.3 e versioni precedenti, se vuoi che la tua app recuperi un file da un'altra app, deve richiamare un intent come ACTION_PICK o ACTION_GET_CONTENT. L'utente seleziona quindi una singola app da cui scegliere un file. L'app selezionata deve fornire un'interfaccia utente per consentire all'utente di sfogliare e scegliere tra i file disponibili.

Su Android 4.4 (livello API 19) e versioni successive, hai la possibilità di utilizzare l'intent ACTION_OPEN_DOCUMENT, che mostra un selettore controllato dal sistema che consente all'utente di sfogliare tutti i file resi disponibili da altre app. Da questa unica interfaccia utente, l'utente può scegliere un file da una qualsiasi delle app supportate.

Su Android 5.0 (livello API 21) e versioni successive, puoi anche utilizzare l'intent ACTION_OPEN_DOCUMENT_TREE, che consente all'utente di scegliere una directory a cui accedere un'app client.

Nota: ACTION_OPEN_DOCUMENT non sostituisce ACTION_GET_CONTENT. La modalità utilizzata dipende dalle esigenze dell'app:

• Usa ACTION_GET_CONTENT se vuoi che l'app leggi o importi dati. Con questo approccio, l'app importa una copia dei dati, ad esempio un file immagine.
• Utilizza ACTION_OPEN_DOCUMENT se vuoi che la tua app abbia accesso permanente e a lungo termine ai documenti di proprietà di un fornitore di documenti. Un esempio è un'app di fotoritocco che consente agli utenti di modificare le immagini archiviate in un fornitore di documenti.

Per ulteriori informazioni su come supportare la navigazione di file e directory utilizzando l'interfaccia utente del selettore di sistema, consulta la guida relativa all'accesso a documenti e ad altri file.

Risorse aggiuntive

Per ulteriori informazioni sui provider di documenti, consulta le seguenti risorse:

Samples

• StorageProvider

Video

• DevBytes: framework di accesso allo spazio di archiviazione per Android 4.4: provider
• File virtuali in Storage Access Framework