Per offrire agli utenti un maggiore controllo sui propri file e limitare l'ingombro dei file, Android 10 ha introdotto un nuovo paradigma di archiviazione per le app chiamato archiviazione con ambito. L'archiviazione con ambito cambia il modo in cui le app archiviano e accedono ai file nella memoria esterna di un dispositivo. Per aiutarti a eseguire la migrazione della tua app in modo che supporti l'archiviazione con ambito, segui le best practice per i casi d'uso di archiviazione comuni descritti in questa guida. I casi d'uso sono organizzati in due categorie: gestione di file multimediali e gestione di file non multimediali.
Per scoprire di più su come archiviare e accedere ai file su Android, consulta le guide di formazione sullo spazio di archiviazione.
Gestire i file multimediali
Questa sezione descrive alcuni dei casi d'uso comuni per la gestione di file multimediali (video, file di immagini e audio) e illustra l'approccio generale che la tua app può utilizzare. La tabella riportata di seguito riassume ciascuno di questi casi d'uso e contiene i link a ciascuna sezione contenente ulteriori dettagli.
Caso d'uso | Riepilogo |
---|---|
Mostra tutti i file immagine o video | Utilizza lo stesso approccio per tutte le versioni di Android. |
Mostrare immagini o video da una determinata cartella | Utilizza lo stesso approccio per tutte le versioni di Android. |
Accedere alle informazioni sulla posizione dalle foto | Se la tua app utilizza l'archiviazione con ambito, scegli un solo approccio. Utilizza un approccio diverso se la tua app disattiva l'archiviazione con ambito. |
Definire la posizione di archiviazione per i nuovi download | Se la tua app utilizza l'archiviazione con ambito, scegli un solo approccio. Utilizza un approccio diverso se la tua app disattiva l'archiviazione con ambito. |
Esportare i file multimediali degli utenti su un dispositivo | Utilizza lo stesso approccio per tutte le versioni di Android. |
Modifica o elimina più file multimediali con una singola operazione | Usa un unico approccio per Android 11. Per Android 10, disattiva l'archiviazione con ambito e utilizza invece l'approccio per Android 9 e versioni precedenti. |
Importa una singola immagine già esistente | Utilizza lo stesso approccio per tutte le versioni di Android. |
Acquisire una singola immagine | Utilizza lo stesso approccio per tutte le versioni di Android. |
Condividere file multimediali con altre app | Utilizza lo stesso approccio per tutte le versioni di Android. |
Condividere file multimediali con un'app specifica | Utilizza lo stesso approccio per tutte le versioni di Android. |
Accedi ai file da codice o librerie che utilizzano percorsi di file diretti | Usa un unico approccio per Android 11. Per Android 10, disattiva l'archiviazione con ambito e utilizza invece l'approccio per Android 9 e versioni precedenti. |
Mostra file di immagini o video da più cartelle
Esegui una query su una raccolta di contenuti multimediali utilizzando l'API query()
. Per filtrare o ordinare i file multimediali, regola i parametri projection
, selection
,
selectionArgs
e sortOrder
.
Mostra immagini o video da una determinata cartella
Utilizza questo approccio:
- Seguendo le best practice descritte in Richiedere le autorizzazioni app, richiedi l'autorizzazione
READ_EXTERNAL_STORAGE
. - Recupera i file multimediali in base al valore di
MediaColumns.DATA
, che contiene il percorso assoluto del file system dell'elemento multimediale sul disco.
Nota:quando accedi a un file multimediale esistente, puoi utilizzare il valore
della colonna DATA
nella logica. Il motivo è che questo valore ha un percorso file valido.
Tuttavia, non dare per scontato che il file sia sempre disponibile. Preparati a gestire eventuali errori di I/O basati su file che potrebbero verificarsi.
Per creare o aggiornare un file multimediale, invece, non utilizzare la colonna DATA
. Utilizza invece le colonne DISPLAY_NAME
e
RELATIVE_PATH
.
Accedi alle informazioni sulla posizione dalle foto
Se l'app utilizza l'archiviazione con ambito, segui i passaggi descritti nella sezione Informazioni sulla posizione nelle fotografie della guida all'archiviazione dei contenuti multimediali.
Definisci la posizione di archiviazione per i nuovi download
Se la tua app utilizza l'archiviazione con ambito, presta attenzione alla posizione in cui scegli di archiviare i file multimediali che scarichi.
Se altre app richiedono l'accesso ai file, valuta l'utilizzo di raccolte multimediali ben definite per i download o le raccolte di documenti.
Su Android 11 e versioni successive, i file all'interno della directory esterna specifica delle app non sono accessibili alle altre app, anche se utilizzi DownloadManager
per recuperarli.
Esportare i file multimediali degli utenti su un dispositivo
Definisci una posizione predefinita appropriata in cui archiviare i file multimediali dell'utente:
- Consenti agli utenti di scegliere se rendere i file multimediali leggibili o meno da altre app, utilizzando lo spazio di archiviazione specifico dell'app o lo spazio di archiviazione condiviso.
- Consenti agli utenti di esportare i file dalle directory specifiche delle app in una posizione più accessibile in generale. Utilizza le raccolte di immagini, video e audio di MediaStore per esportare i file multimediali nella galleria del dispositivo.
Modificare o eliminare più file multimediali in una singola operazione
Incorpora una logica basata sulle versioni di Android su cui viene eseguita l'app.
In esecuzione su Android 11
Utilizza questo approccio:
- Crea un intent in attesa per la richiesta di scrittura o eliminazione dell'app utilizzando
MediaStore.createWriteRequest()
oMediaStore.createTrashRequest()
, quindi chiedi all'utente l'autorizzazione per modificare un insieme di file richiamando questo intento. Valuta la risposta dell'utente:
- Se l'autorizzazione è stata concessa, procedi con l'operazione di modifica o eliminazione.
- Se l'autorizzazione non è stata concessa, spiega all'utente perché la funzionalità nella tua app richiede l'autorizzazione.
Scopri di più su come gestire gruppi di file multimediali utilizzando questi metodi disponibili su Android 11 e versioni successive.
In esecuzione su Android 10
Se la tua app ha come target Android 10 (livello API 29), disattiva l'archiviazione con ambito e continua a utilizzare l'approccio per Android 9 e versioni precedenti per eseguire questa operazione.
Con Android 9 o versioni precedenti
Utilizza questo approccio:
- Seguendo le best practice descritte in Richiedere le autorizzazioni app, richiedi l'autorizzazione
WRITE_EXTERNAL_STORAGE
. - Utilizza l'API
MediaStore
per modificare o eliminare i file multimediali.
Importa una singola immagine già esistente
Quando vuoi importare una singola immagine già esistente (ad esempio da utilizzare come foto per il profilo di un utente), la tua app può usare la propria UI per l'operazione oppure il selettore di sistema.
Presenta la tua interfaccia utente
Utilizza questo approccio:
- Seguendo le best practice descritte in Richiedere le autorizzazioni app, richiedi l'autorizzazione
READ_EXTERNAL_STORAGE
. - Utilizza l'API
query()
per eseguire query su una raccolta di contenuti multimediali. - Visualizza i risultati nell'interfaccia utente personalizzata della tua app.
Utilizza il selettore di sistema
Utilizza l'intent ACTION_GET_CONTENT
, che chiede all'utente di scegliere un'immagine da importare.
Se vuoi filtrare i tipi di immagini che il selettore di sistema presenta all'utente tra cui scegliere, puoi utilizzare setType()
o EXTRA_MIME_TYPES
.
Acquisisci una singola immagine
Quando vuoi acquisire una singola immagine da utilizzare nella tua app (ad esempio da utilizzare come foto per il profilo di un utente), utilizza l'intent ACTION_IMAGE_CAPTURE
per chiedere all'utente di scattare una foto con la fotocamera del dispositivo. Il sistema
archivia la foto acquisita nella tabella MediaStore.Images
.
Condividere file multimediali con altre app
Utilizza il metodo insert()
per aggiungere record direttamente in MediaStore. Per ulteriori informazioni, consulta la sezione Aggiungere un elemento della guida all'archiviazione multimediale.
Condividere file multimediali con un'app specifica
Utilizza il componente FileProvider
di Android, come descritto nella guida Configurare la condivisione
file.
Accedi ai file da codice o librerie che utilizzano percorsi di file diretti
Incorpora una logica basata sulle versioni di Android su cui viene eseguita l'app.
In esecuzione su Android 11
Utilizza questo approccio:
- Seguendo le best practice descritte in Richiedere le autorizzazioni app, richiedi l'autorizzazione
READ_EXTERNAL_STORAGE
. - Accedi ai file utilizzando percorsi diretti.
Per ulteriori informazioni, consulta la sezione su come aprire i file multimediali utilizzando i percorsi di file diretti.
In esecuzione su Android 10
Se la tua app ha come target Android 10 (livello API 29), disattiva l'archiviazione con ambito e continua a utilizzare l'approccio per Android 9 e versioni precedenti per eseguire questa operazione.
Con Android 9 o versioni precedenti
Utilizza questo approccio:
- Seguendo le best practice descritte in Richiedere le autorizzazioni app, richiedi l'autorizzazione
WRITE_EXTERNAL_STORAGE
. - Accedi ai file utilizzando percorsi diretti.
Gestire i file non multimediali
Questa sezione descrive alcuni dei casi d'uso comuni per la gestione di file non multimediali e illustra l'approccio generale che la tua app può utilizzare. La seguente tabella riassume ciascuno di questi casi d'uso e fornisce un link a ciascuna sezione che contiene ulteriori dettagli.
Caso d'uso | Riepilogo |
---|---|
Aprire il file di un documento | Utilizza lo stesso approccio per tutte le versioni di Android. |
Scrittura su file su volumi di archiviazione secondari | Usa un unico approccio per Android 11. Utilizza un approccio diverso per le versioni precedenti di Android. |
Eseguire la migrazione di file esistenti da una posizione di archiviazione precedente | Se possibile, esegui la migrazione dei file all'archiviazione con ambito. Disattiva l'archiviazione con ambito per Android 10 quando necessario. |
Condividere contenuti con altre app | Utilizza lo stesso approccio per tutte le versioni di Android. |
Memorizzare nella cache i file non multimediali | Utilizza lo stesso approccio per tutte le versioni di Android. |
Esportare file non multimediali su un dispositivo | Se la tua app utilizza l'archiviazione con ambito, scegli un solo approccio. Utilizza un approccio diverso se la tua app disattiva l'archiviazione con ambito. |
Apri il file di un documento
Utilizza l'intent ACTION_OPEN_DOCUMENT
per chiedere all'utente di scegliere un file da aprire utilizzando il selettore di sistema. Se vuoi filtrare i tipi di file che il selettore di sistema presenterà all'utente tra cui scegliere, puoi utilizzare setType()
o EXTRA_MIME_TYPES
.
Ad esempio, potresti trovare tutti i file PDF, ODT e TXT utilizzando il seguente codice:
Kotlin
startActivityForResult( Intent(Intent.ACTION_OPEN_DOCUMENT).apply { addCategory(Intent.CATEGORY_OPENABLE) type = "*/*" putExtra(Intent.EXTRA_MIME_TYPES, arrayOf( "application/pdf", // .pdf "application/vnd.oasis.opendocument.text", // .odt "text/plain" // .txt )) }, REQUEST_CODE )
Java
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); intent.addCategory(Intent.CATEGORY_OPENABLE); intent.setType("*/*"); intent.putExtra(Intent.EXTRA_MIME_TYPES, new String[] { "application/pdf", // .pdf "application/vnd.oasis.opendocument.text", // .odt "text/plain" // .txt }); startActivityForResult(intent, REQUEST_CODE);
Scrivi su file su volumi di archiviazione secondari
I volumi di archiviazione secondari includono le schede SD. Puoi accedere alle informazioni su un determinato volume di archiviazione utilizzando la classe StorageVolume
.
Incorpora una logica basata sulla versione di Android su cui viene eseguita l'app.
In esecuzione su Android 11
Utilizza questo approccio:
- Utilizza il modello di archiviazione con ambito.
- Scegli come target Android 10 (livello API 29) o versioni precedenti.
- Dichiara l'autorizzazione
WRITE_EXTERNAL_STORAGE
. - Esegui uno dei seguenti tipi di accesso:
- Accesso ai file con l'API
MediaStore
. - Accesso diretto al percorso file utilizzando API come
File
ofopen()
.
- Accesso ai file con l'API
Esecuzione su versioni precedenti
Utilizzare il framework di Storage Access, che consente agli utenti di selezionare la località su un volume di archiviazione secondario in cui l'app può scrivere il file.
Eseguire la migrazione dei file esistenti da un percorso di archiviazione precedente
Una directory è considerata una posizione di archiviazione legacy se non è una directory specifica dell'app o una directory condivisa pubblica. Se l'app crea o consuma file in una posizione di archiviazione legacy, ti consigliamo di eseguire la migrazione dei file dell'app in posizioni accessibili con l'archiviazione con ambito e di apportare le eventuali modifiche necessarie all'app per lavorare con i file nello spazio di archiviazione con ambito.
Mantenere l'accesso alla posizione di archiviazione precedente per la migrazione dei dati
L'app deve mantenere l'accesso alla posizione di archiviazione precedente per eseguire la migrazione dei file dell'app in posizioni accessibili con l'archiviazione con ambito. L'approccio da utilizzare dipende dal livello API target della tua app.
Se la tua app ha come target Android 11
Imposta il flag
preserveLegacyExternalStorage
sutrue
per preservare il modello di archiviazione legacy in modo che la tua app possa eseguire la migrazione dei dati di un utente quando esegue l'upgrade alla nuova versione dell'app che ha come target Android 11.Continua a disattivare lo spazio di archiviazione con ambito in modo che l'app possa continuare ad accedere ai tuoi file nella posizione di archiviazione precedente sui dispositivi Android 10.
Se la tua app ha come target Android 10
Disattiva l'archiviazione con ambito per semplificare il comportamento della tua app nelle varie versioni di Android.
Esegui la migrazione dei dati dell'app
Quando la tua app è pronta per la migrazione, utilizza il seguente approccio:
- Scegli come target Android 10 o versioni precedenti.
- Disattiva l'archiviazione con ambito in modo che la tua app abbia accesso ai file di cui devi eseguire la migrazione.
-
Esegui il deployment del codice che utilizza l'API
File
per spostare i file dalla posizione attuale in/sdcard/
a una posizione accessibile con l'archiviazione con ambito:- Sposta tutti i file privati dell'app nella directory restituita dal metodo
getExternalFilesDir()
. - Sposta tutti i file non multimediali condivisi in una sottodirectory dedicata all'app della
directory
Downloads/
.
- Sposta tutti i file privati dell'app nella directory restituita dal metodo
- Rimuovi le directory di archiviazione legacy dell'app dalla
directory
/sdcard/
.
Dopo aver installato la nuova versione dell'app, gli utenti completano il processo di migrazione dei dati sui propri dispositivi. Puoi monitorare il processo di migrazione della base utenti creando un evento di analisi.
Dopo che gli utenti hanno eseguito la migrazione dei propri dati, pubblica un altro aggiornamento dell'app per cui hai scelto come target Android 11.
Condividere contenuti con altre app
Per condividere i file dell'app con un'altra app, usa un
FileProvider
. Per le app in cui tutte devono condividere
file tra loro, consigliamo di utilizzare un
fornitore di contenuti per ogni app, quindi di sincronizzare i dati man mano che le app vengono aggiunte alla raccolta.
Memorizza nella cache file non multimediali
L'approccio da utilizzare dipende dal tipo di file che devi memorizzare nella cache.
- File di piccole dimensioni o file che contengono informazioni sensibili: usa
Context#getCacheDir()
. - File di grandi dimensioni o file che non contengono informazioni sensibili: utilizza
Context#getExternalCacheDir()
.
Esportare file non multimediali su un dispositivo
Definisci un percorso predefinito appropriato in cui archiviare i file non multimediali. Consenti agli utenti di esportare i file dalle directory specifiche delle app in una posizione più accessibile in generale. Utilizza i download di MediaStore o le raccolte di documenti per esportare file non multimediali sul dispositivo.
Disattiva temporaneamente l'archiviazione con ambito
Prima che la tua app sia completamente compatibile con l'archiviazione con ambito, puoi disattivarla temporaneamente, sia nei test sia nell'app di produzione.
Disattiva nei test
Su Android 10 (livello API 29) e versioni successive, i test dell'app vengono eseguiti in una sandbox di archiviazione per impostazione predefinita. Questa sandbox impedisce alla tua app di accedere ai file esterni alla directory specifica dell'app e alle directory condivise pubblicamente.
Se un test produce file per l'host, ad esempio screenshot, dati di debug, dati di copertura o metriche delle prestazioni, puoi scrivere questi file nelle directory globali. A questo scopo, aggiungi il seguente flag al cablaggio pertinente che
richiama am instrument
:
-e no-isolated-storage 1
Questo flag influisce su tutti il comportamento dello scenario di test instrumentato e interessa tutto il codice di test richiamato. Di conseguenza, se utilizzi questo flag non puoi convalidare la compatibilità dell'app con l'archiviazione con ambito. Per l'output di test, è preferibile scrivere
in uno spazio di archiviazione con ambito app leggibile dalla shell. Puoi quindi eseguire il pull della directory
con ambito app. Per determinare da quale directory eseguire il pull, chiama
getExternalMediaDirs()
.
Disattiva nella tua app di produzione
Se la tua app ha come target Android 10 (livello API 29) o versioni precedenti, puoi disattivare temporaneamente lo spazio di archiviazione con ambito nell'app di produzione. Se scegli come target Android 10, tuttavia, devi impostare il valore di requestLegacyExternalStorage
su true
nel file manifest dell'app:
<manifest ... > <!-- This attribute is "false" by default on apps targeting Android 10. --> <application android:requestLegacyExternalStorage="true" ... > ... </application> </manifest>
Per testare il comportamento di un'app che ha come target Android 10 o versioni precedenti quando
utilizza l'archiviazione con ambito, puoi attivare questo comportamento impostando il valore di
requestLegacyExternalStorage
su false
. Se stai eseguendo il test su un dispositivo con Android 11, puoi anche utilizzare i flag di compatibilità delle app per verificare il comportamento della tua app con o senza spazio di archiviazione nell'ambito.
Risorse aggiuntive
Per ulteriori informazioni sullo spazio di archiviazione di Android, visualizza i seguenti materiali: