Questa pagina è stata tradotta dall'API Cloud Translation.

Aprire i file utilizzando Storage Access Framework
Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

I servizi di archiviazione locale o cloud possono partecipare a questo ecosistema implementando un DocumentsProvider che incapsula i loro servizi. Le app client che devono accedere ai documenti di un fornitore possono integrarsi con la piattaforma SAF con poche righe di codice.

Il SAF include quanto segue:

Fornitore di documenti:un fornitore di contenuti che consente a un servizio di archiviazione, come Google Drive, di mostrare i file che gestisce. Un fornitore 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 la modalità di memorizzazione fisica dei dati da parte del fornitore di documenti dipende da te. La piattaforma Android include diversi fornitori di documenti integrati, come Download, Immagini e Video.
App client: un'app personalizzata che richiama le azioni di intent ACTION_CREATE_DOCUMENT,ACTION_OPEN_DOCUMENT eACTION_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 di 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 file sul provider.
Supporta più account utente e origini temporanee come i fornitori di archiviazione USB, che vengono visualizzati solo se l'unità è collegata.

Panoramica

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

**Figura 1.** Modello di dati del fornitore di documenti. Un nodo principale rimanda a un singolo documento, che avvia la distribuzione dell'albero.

Nota:

Ogni fornitore di documenti segnala una o più radici, che sono i punti di partenza per esplorare un albero di documenti. Ogni radice ha un COLUMN_ROOT_ID univoco e fa riferimento a un documento (una directory) che rappresenta i contenuti sotto quella radice. Le radici sono dinamiche per impostazione predefinita per supportare casi d'uso come più account, dispositivi di archiviazione USB temporanei o accesso e uscita degli utenti.
Sotto ogni radice è presente un singolo documento. Il documento rimanda da 1 a N documenti, ciascuno dei quali a sua volta può fare riferimento da 1 a N documenti.
Ogni backend di archiviazione mostra singoli file e directory facendovi riferimento con un COLUMN_DOCUMENT_ID univoco. Gli ID documento sono univoci e non cambiano una volta emessi, poiché vengono utilizzati per le autorizzazioni URI permanenti durante i riavvii del dispositivo.
I documenti possono essere un file apribile con un tipo MIME specifico o una directory contenente altri documenti con il tipo MIME MIME_TYPE_DIR.
Ogni documento può avere funzionalità diverse, come descritto daCOLUMN_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 di dati del provider di documenti si basa su una gerarchia di file tradizionale. Tuttavia, puoi memorizzare fisicamente i dati come preferisci, purché tu possa accedervi utilizzando l'DocumentsProvider API. Ad esempio, puoi utilizzare lo spazio di archiviazione sul cloud basato su tag per i tuoi dati.

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

**Figura 2**. Flusso del framework Storage Access.

Nota:

In SAF, i fornitori e i clienti non interagiscono direttamente. Un client richiede l'autorizzazione per interagire con i file, ovvero per leggerli, modificarli, crearli o eliminarli.
L'interazione inizia quando un'applicazione, in questo caso un'app di foto, attiva l'intentACTION_OPEN_DOCUMENT o ACTION_CREATE_DOCUMENT. L'intent può includere filtri per perfezionare ulteriormente i criteri, ad esempio "dammi tutti i file aperti con il tipo MIME "immagine"".
Una volta attivato l'intent, il selettore di sistema si rivolge a ciascun fornitore registrato e mostra all'utente le radici dei contenuti corrispondenti.
Il selettore offre agli utenti un'interfaccia standard per accedere ai documenti, anche quando i provider di documenti sottostanti sono molto diversi. Ad esempio, la figura 2 mostra un provider Google Drive, un provider USB e un provider cloud.

Nella Figura 3, l'utente seleziona la cartella Download da un selettore aperto durante la ricerca di immagini. Il selettore mostra anche tutte le radici disponibili per l'app client.

Selezione della cartella nel selettore di sistema. — **Figura 3.** Selettore che mostra la cartella Download selezionata come posizione di ricerca.

Dopo che l'utente seleziona la cartella Download, vengono visualizzate le immagini. La Figura 4 mostra il risultato di questa procedura. Ora l'utente può interagire con le immagini nel modo supportato dall'app del provider e del client.

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

Scrivere un'app client

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

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

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 un'app client può accedere.

Nota: ACTION_OPEN_DOCUMENT non sostituisce ACTION_GET_CONTENT. Quello che utilizzi dipende dalle esigenze della tua app:

Utilizza ACTION_GET_CONTENT se vuoi che la tua app legga o importi i dati. Con questo approccio, l'app importa una copia dei dati, come 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 memorizzate in un provider di documenti.

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