DataStore   Parte di Android Jetpack.

Prova con Kotlin Multiplatform

Kotlin Multiplatform consente di condividere il livello dati con altre piattaforme. Scopri come configurare e utilizzare DataStore in KMP

Configurare DataStore per KMP →

Jetpack DataStore è una soluzione di archiviazione dei dati che ti consente di archiviare coppie chiave-valore o oggetti digitati con protocol buffer. DataStore utilizza le coroutine Kotlin e Flow per archiviare i dati in modo asincrono, coerente e transazionale.

Se utilizzi SharedPreferences per archiviare i dati, valuta la possibilità di eseguire la migrazione a DataStore.

API DataStore

L'interfaccia DataStore fornisce la seguente API:

1. Un flusso che può essere utilizzato per leggere i dati da DataStore

   val data: Flow<T>
   

2. Una funzione per aggiornare i dati in DataStore

   suspend updateData(transform: suspend (t) -> T)
   

Configurazioni di DataStore

Se vuoi archiviare e accedere ai dati utilizzando le chiavi, utilizza l'implementazione Preferences DataStore, che non richiede uno schema predefinito e non fornisce la sicurezza dei tipi. Ha un'API simile a SharedPreferences, ma non presenta gli svantaggi associati alle preferenze condivise.

DataStore consente di rendere persistenti le classi personalizzate. Per farlo, devi definire uno schema per i dati e fornire un Serializer per convertirli in un formato persistente. Puoi scegliere di utilizzare Protocol Buffers, JSON o qualsiasi altra strategia di serializzazione.

Configurazione

Per utilizzare Jetpack DataStore nella tua app, aggiungi quanto segue al file Gradle a seconda dell'implementazione che vuoi utilizzare:

Datastore delle preferenze

Aggiungi le seguenti righe alla sezione delle dipendenze del file Gradle:

    dependencies {
        // Preferences DataStore (SharedPreferences like APIs)
        implementation "androidx.datastore:datastore-preferences:1.2.1"

        // Alternatively - without an Android dependency.
        implementation "androidx.datastore:datastore-preferences-core:1.2.1"
    }
    

    dependencies {
        // Preferences DataStore (SharedPreferences like APIs)
        implementation("androidx.datastore:datastore-preferences:1.2.1")

        // Alternatively - without an Android dependency.
        implementation("androidx.datastore:datastore-preferences-core:1.2.1")
    }
    

Per aggiungere il supporto facoltativo di RxJava, aggiungi le seguenti dipendenze:

    dependencies {
        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.2.1"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.2.1"
    }
    

    dependencies {
        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.2.1")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.2.1")
    }
    

DataStore

Aggiungi le seguenti righe alla sezione delle dipendenze del file Gradle:

    dependencies {
        // Typed DataStore for custom data objects (for example, using Proto or JSON).
        implementation "androidx.datastore:datastore:1.2.1"

        // Alternatively - without an Android dependency.
        implementation "androidx.datastore:datastore-core:1.2.1"
    }
    

    dependencies {
        // Typed DataStore for custom data objects (for example, using Proto or JSON).
        implementation("androidx.datastore:datastore:1.2.1")

        // Alternatively - without an Android dependency.
        implementation("androidx.datastore:datastore-core:1.2.1")
    }
    

Aggiungi le seguenti dipendenze facoltative per il supporto di RxJava:

    dependencies {
        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.2.1"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.2.1"
    }
    

    dependencies {
        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.2.1")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.2.1")
    }
    

Per serializzare i contenuti, aggiungi le dipendenze per la serializzazione di Protocol Buffer o JSON.

Serializzazione JSON

Per utilizzare la serializzazione JSON, aggiungi quanto segue al file Gradle:

    plugins {
        id("org.jetbrains.kotlin.plugin.serialization") version "2.2.20"
    }

    dependencies {
        implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0"
    }
    

    plugins {
        id("org.jetbrains.kotlin.plugin.serialization") version "2.2.20"
    }

    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
    }
    

Serializzazione Protobuf

Per utilizzare la serializzazione Protobuf, aggiungi quanto segue al file Gradle:

    plugins {
        id("com.google.protobuf") version "0.9.5"
    }
    dependencies {
        implementation "com.google.protobuf:protobuf-kotlin-lite:4.32.1"

    }

    protobuf {
        protoc {
            artifact = "com.google.protobuf:protoc:4.32.1"
        }
        generateProtoTasks {
            all().forEach { task ->
                task.builtins {
                    create("java") {
                        option("lite")
                    }
                    create("kotlin")
                }
            }
        }
    }
    

    plugins {
        id("com.google.protobuf") version "0.9.5"
    }
    dependencies {
        implementation("com.google.protobuf:protobuf-kotlin-lite:4.32.1")
    }

    protobuf {
        protoc {
            artifact = "com.google.protobuf:protoc:4.32.1"
        }
        generateProtoTasks {
            all().forEach { task ->
                task.builtins {
                    create("java") {
                        option("lite")
                    }
                    create("kotlin")
                }
            }
        }
    }
    

Utilizzare DataStore correttamente

Per utilizzare DataStore correttamente, tieni sempre presente le seguenti regole:

1. Non creare mai più di un'istanza di DataStore per un determinato file nello stesso processo. In questo modo, tutte le funzionalità di DataStore potrebbero non funzionare più. Se sono attivi più DataStore per un determinato file nello stesso processo, DataStore genererà IllegalStateException durante la lettura o l'aggiornamento dei dati.

2. Il tipo generico di DataStore<T> deve essere immutabile. La modifica di un tipo utilizzato in DataStore invalida la coerenza fornita da DataStore e crea bug potenzialmente gravi e difficili da individuare. Ti consigliamo di utilizzare i buffer del protocollo, che contribuiscono a garantire l'immutabilità, un'API chiara e una serializzazione efficiente.

3. Non combinare gli utilizzi di SingleProcessDataStore e MultiProcessDataStore per lo stesso file. Se intendi accedere a DataStore da più di un processo, devi utilizzare MultiProcessDataStore.

Definizione dei dati

val EXAMPLE_COUNTER = intPreferencesKey("example_counter")

@Serializable
data class Settings(
    val exampleCounter: Int
)

object SettingsSerializer : Serializer<Settings> {

    override val defaultValue: Settings = Settings(exampleCounter = 0)

    override suspend fun readFrom(input: InputStream): Settings =
        try {
            Json.decodeFromString<Settings>(
                input.readBytes().decodeToString()
            )
        } catch (serialization: SerializationException) {
            throw CorruptionException("Unable to read Settings", serialization)
        }

    override suspend fun writeTo(t: Settings, output: OutputStream) {
        output.write(
            Json.encodeToString(t)
                .encodeToByteArray()
        )
    }
}

syntax = "proto3";

option java_package = "com.example.datastore.snippets.proto";
option java_multiple_files = true;

message Settings {
  int32 example_counter = 1;
}

object SettingsSerializer : Serializer<Settings> {
    override val defaultValue: Settings = Settings.getDefaultInstance()

    override suspend fun readFrom(input: InputStream): Settings {
        try {
            return Settings.parseFrom(input)
        } catch (exception: InvalidProtocolBufferException) {
            throw CorruptionException("Cannot read proto.", exception)
        }
    }

    override suspend fun writeTo(t: Settings, output: OutputStream) {
        return t.writeTo(output)
    }
}

Crea un datastore

Devi specificare un nome per il file utilizzato per rendere persistenti i dati.

// At the top level of your kotlin file:
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")

val Context.dataStore: DataStore<Settings> by dataStore(
    fileName = "settings.json",
    serializer = SettingsSerializer,
)

val Context.dataStore: DataStore<Settings> by dataStore(
    fileName = "settings.pb",
    serializer = SettingsSerializer,
)

Leggi da DataStore

Devi specificare un nome per il file utilizzato per rendere persistenti i dati.

fun counterFlow(): Flow<Int> = context.dataStore.data.map { preferences ->
    preferences[EXAMPLE_COUNTER] ?: 0
}

fun counterFlow(): Flow<Int> = context.dataStore.data.map { settings ->
    settings.exampleCounter
}

fun counterFlow(): Flow<Int> = context.dataStore.data.map { settings ->
    settings.exampleCounter
}

Utilizza collectAsStateWithLifecycle per utilizzare Flow prodotto da un ViewModel in un componibile. In questo modo, il flusso DataStore viene convertito in modo sicuro in Compose State, che attiva la ricomposizione.

@Composable
fun SomeScreen(counterFlow: Flow<Int>) {
  val counter by counterFlow.collectAsStateWithLifecycle(initialValue = 0)
  Text(text = "Example counter: ${counter}")
}

Per saperne di più su collectAsStateWithLifecycle, consulta Stato e Jetpack Compose.

Scrivi in DataStore

DataStore fornisce una funzione updateData che aggiorna in modo transazionale un oggetto archiviato. updateData fornisce lo stato attuale dei dati come istanza del tipo di dati e aggiorna i dati in modo transazionale in un'operazione di lettura-scrittura-modifica atomica. Tutto il codice nel blocco updateData viene considerato come una singola transazione.

suspend fun incrementCounter() {
    context.dataStore.updateData {
        it.toMutablePreferences().also { preferences ->
            preferences[EXAMPLE_COUNTER] = (preferences[EXAMPLE_COUNTER] ?: 0) + 1
        }
    }
}

suspend fun incrementCounter() {
    context.dataStore.updateData { settings ->
        settings.copy(exampleCounter = settings.exampleCounter + 1)
    }
}

suspend fun incrementCounter() {
    context.dataStore.updateData { settings ->
        settings.copy { exampleCounter = exampleCounter + 1 }
    }
}

Utilizzare DataStore in un'app Compose

Per utilizzare DataStore in un'app Compose, segui le linee guida per l'architettura delle app per Android mantenendo le operazioni DataStore nel livello dati (ad esempio un repository) ed esponendo i dati alla UI tramite un ViewModel.

Evita di leggere o scrivere direttamente in DataStore all'interno delle tue funzioni componibili.

1. Esporre DataStore tramite un ViewModel. Passa il repository (che contiene DataStore) in ViewModel e converti Flow in StateFlow in modo che l'interfaccia utente possa osservarlo facilmente, come mostrato nel seguente snippet:

   class SettingsViewModel(
       private val userPreferencesRepository: UserPreferencesRepository
   ) : ViewModel() {
   
       // Expose the DataStore flow as a StateFlow for Compose
       val userSettings: StateFlow<UserSettings> = userPreferencesRepository.userSettingsFlow
           .stateIn(
               scope = viewModelScope,
               started = SharingStarted.WhileSubscribed(5000),
               initialValue = UserSettings.getDefaultInstance()
           )
   
       fun updateCounter(newValue: Int) {
           viewModelScope.launch {
               userPreferencesRepository.updateCounter(newValue)
           }
       }
   }
   

2. Osserva e scrivi dal tuo composable. Utilizza collectAsStateWithLifecycle per osservare in modo sicuro StateFlow nella tua UI e chiama le funzioni ViewModel per gestire le scritture, come mostrato nel seguente snippet:

   @Composable
   fun SettingsScreen(
       viewModel: SettingsViewModel = viewModel()
   ) {
       // Safely collect the state
       val settings by viewModel.userSettings.collectAsStateWithLifecycle()
   
       Column(modifier = Modifier.padding(16.dp)) {
           Text(text = "Current counter: ${settings.counter}")
   
           Spacer(modifier = Modifier.height(8.dp))
   
           Button(onClick = { viewModel.updateCounter(settings.counter + 1) }) {
               Text("Increment Counter")
           }
       }
   }
   

Utilizzare DataStore nel codice multiprocesso

Puoi configurare DataStore per accedere agli stessi dati in processi diversi con le stesse proprietà di coerenza dei dati di un singolo processo. In particolare, DataStore fornisce le seguenti proprietà:

• Le letture restituiscono solo i dati salvati su disco.
• Coerenza read-after-write.
• Le scritture vengono serializzate.
• Le letture non vengono mai bloccate dalle scritture.

Considera un'applicazione di esempio con un servizio e un'attività in cui il servizio viene eseguito in un processo separato e aggiorna periodicamente DataStore.

Questo esempio utilizza un datastore JSON, ma puoi utilizzare anche un datastore Preferences o Proto.

@Serializable
data class Time(
    val lastUpdateMillis: Long
)

Un serializzatore indica a DataStore come leggere e scrivere il tipo di dati. Assicurati di includere un valore predefinito per il serializzatore da utilizzare se non è ancora stato creato alcun file. Di seguito è riportato un esempio di implementazione che utilizza kotlinx.serialization:

object TimeSerializer : Serializer<Time> {

    override val defaultValue: Time = Time(lastUpdateMillis = 0L)

    override suspend fun readFrom(input: InputStream): Time =
        try {
            Json.decodeFromString<Time>(
                input.readBytes().decodeToString()
            )
        } catch (serialization: SerializationException) {
            throw CorruptionException("Unable to read Time", serialization)
        }

    override suspend fun writeTo(t: Time, output: OutputStream) {
        output.write(
            Json.encodeToString(t)
                .encodeToByteArray()
        )
    }
}

Per poter utilizzare DataStore in diversi processi, devi creare l'oggetto DataStore utilizzando MultiProcessDataStoreFactory sia per il codice dell'app che per quello del servizio:

val dataStore = MultiProcessDataStoreFactory.create(
    serializer = TimeSerializer,
    produceFile = {
        File("${context.filesDir.path}/time.pb")
    },
    corruptionHandler = null
)

Aggiungi quanto segue a AndroidManifiest.xml:

<service
    android:name=".TimestampUpdateService"
    android:process=":my_process_id" />

Il servizio chiama periodicamente updateLastUpdateTime, che scrive nel datastore utilizzando updateData.

suspend fun updateLastUpdateTime() {
    dataStore.updateData { time ->
        time.copy(lastUpdateMillis = System.currentTimeMillis())
    }
}

L'app legge il valore scritto dal servizio utilizzando il flusso di dati:

fun timeFlow(): Flow<Long> = dataStore.data.map { time ->
    time.lastUpdateMillis
}

Ora possiamo raggruppare tutte queste funzioni in una classe chiamata MultiProcessDataStore e utilizzarla in un'app.

Ecco il codice di servizio:

class TimestampUpdateService : Service() {
    val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
    val multiProcessDataStore by lazy { MultiProcessDataStore(applicationContext) }


    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        serviceScope.launch {
            while (true) {
                multiProcessDataStore.updateLastUpdateTime()
                delay(1000)
            }
        }
        return START_NOT_STICKY
    }

    override fun onDestroy() {
        super.onDestroy()
        serviceScope.cancel()
    }
}

e il codice dell'app:

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val multiProcessDataStore = remember(context) { MultiProcessDataStore(context) }

// Display time written by other process.
val lastUpdateTime by multiProcessDataStore.timeFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Last updated: $lastUpdateTime",
    fontSize = 25.sp
)

DisposableEffect(context) {
    val serviceIntent = Intent(context, TimestampUpdateService::class.java)
    context.startService(serviceIntent)
    onDispose {
        context.stopService(serviceIntent)
    }
}

Puoi utilizzare l'inserimento delle dipendenze Hilt in modo che l'istanza DataStore sia univoca per processo:

@Provides
@Singleton
fun provideDataStore(@ApplicationContext context: Context): DataStore<Settings> =
   MultiProcessDataStoreFactory.create(...)

Gestire il danneggiamento dei file

In rari casi, il file persistente su disco di DataStore potrebbe danneggiarsi. Per impostazione predefinita, DataStore non esegue automaticamente il recupero dal danneggiamento e i tentativi di lettura causeranno la generazione di un CorruptionException da parte del sistema.

DataStore offre un'API di gestione del danneggiamento che può aiutarti a eseguire il ripristino in modo controllato in questo scenario ed evitare di generare l'eccezione. Se configurato, il gestore del danneggiamento sostituisce il file danneggiato con uno nuovo contenente un valore predefinito predefinito.

Per configurare questo gestore, fornisci un corruptionHandler quando crei l'istanza DataStore in by dataStore o nel metodo factory DataStoreFactory:

val dataStore: DataStore<Settings> = DataStoreFactory.create(
   serializer = SettingsSerializer(),
   produceFile = {
       File("${context.filesDir.path}/myapp.preferences_pb")
   },
   corruptionHandler = ReplaceFileCorruptionHandler { Settings(lastUpdate = 0) }
)

Fornisci feedback

Condividi con noi il tuo feedback e le tue idee tramite queste risorse:

Issue Tracker:

Segnala i problemi per consentirci di correggere i bug.

Risorse aggiuntive

Per saperne di più su Jetpack DataStore, consulta le seguenti risorse aggiuntive:

Esempi

Blog

• Preferisci archiviare i dati con Jetpack DataStore

Codelab

• Utilizzo di Preferences DataStore
• Utilizzo di Proto DataStore