DataStore   Fait partie d'Android Jetpack.

Essayer avec Kotlin Multiplatform

Kotlin Multiplatform permet de partager la couche de données avec d'autres plates-formes. Découvrez comment configurer et utiliser DataStore dans KMP

Configurer DataStore pour KMP →

Jetpack DataStore est une solution de stockage de données qui vous permet de stocker des paires clé-valeur ou des objets typés avec des tampons de protocole. DataStore utilise les coroutines Kotlin et Flow pour stocker les données de manière asynchrone, cohérente et transactionnelle.

Si vous utilisez SharedPreferences pour stocker des données, nous vous recommandons d'effectuer une migration vers DataStore.

API DataStore

L'interface DataStore fournit l'API suivante :

1. Un flux qui peut être utilisé pour lire des données à partir de DataStore

   val data: Flow<T>
   

2. Une fonction permettant de mettre à jour les données dans DataStore

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

Configurations de DataStore

Si vous souhaitez stocker des données et y accéder à l'aide de clés, utilisez l'implémentation Preferences DataStore, qui ne nécessite pas de schéma prédéfini et ne fournit pas de sûreté du typage. Elle dispose d'une SharedPreferences-like API, mais ne présente pas les inconvénients associés aux préférences partagées.

DataStore vous permet de conserver des classes personnalisées. Pour ce faire, vous devez définir un schéma pour les données et fournir un Serializer pour les convertir dans un format persistant. Vous pouvez choisir d'utiliser des tampons de protocole, JSON ou toute autre stratégie de sérialisation.

Configuration

Pour utiliser Jetpack DataStore dans votre application, ajoutez les éléments suivants à votre fichier Gradle en fonction de l'implémentation que vous souhaitez utiliser :

Preferences DataStore

Ajoutez les lignes suivantes à la partie des dépendances de votre fichier 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")
    }
    

Pour ajouter la prise en charge facultative de RxJava, ajoutez les dépendances suivantes :

    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

Ajoutez les lignes suivantes à la partie des dépendances de votre fichier 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")
    }
    

Ajoutez les dépendances facultatives suivantes pour la compatibilité avec 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")
    }
    

Pour sérialiser du contenu, ajoutez des dépendances pour la sérialisation Protocol Buffers ou JSON.

Sérialisation JSON

Pour utiliser la sérialisation JSON, ajoutez les lignes suivantes à votre fichier 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")
    }
    

Sérialisation Protobuf

Pour utiliser la sérialisation Protobuf, ajoutez les lignes suivantes à votre fichier 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")
                }
            }
        }
    }
    

Utiliser correctement DataStore

Pour utiliser correctement DataStore, gardez toujours à l'esprit les règles suivantes :

1. Ne créez jamais plus d'une instance de DataStore pour un fichier donné dans le même processus. En effet, les fonctionnalités de DataStore pourraient ne plus marcher. Si plusieurs instances sont actives pour un fichier donné au cours du même processus, DataStore générera une IllegalStateException lors de la lecture ou de la mise à jour de données.

2. Le type générique de DataStore<T> doit être immuable. La mutation d'un type utilisé dans DataStore annule la cohérence fournie par DataStore et crée des bugs potentiellement graves et difficiles à détecter. Nous vous recommandons d'utiliser des tampons de protocole, qui contribuent à garantir l'immuabilité, une API claire et une sérialisation efficace.

3. N'utilisez pas à la fois SingleProcessDataStore et MultiProcessDataStore pour le même fichier. Si vous avez l'intention d'accéder au DataStore à partir de plusieurs processus, vous devez utiliser MultiProcessDataStore.

Définition des données

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)
    }
}

Créer un DataStore

Vous devez spécifier un nom pour le fichier utilisé pour conserver les données.

// 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,
)

Lire à partir de DataStore

Vous devez spécifier un nom pour le fichier utilisé pour conserver les données.

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
}

Utilisez collectAsStateWithLifecycle pour consommer le Flow produit par un ViewModel dans un composable. Cela convertit en toute sécurité le flux DataStore en état Compose qui déclenche une recomposition.

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

Pour en savoir plus sur collectAsStateWithLifecycle, consultez États et Jetpack Compose.

Écrire dans DataStore

DataStore fournit une fonction updateData qui met à jour un objet stocké de manière transactionnelle. updateData vous donne l'état actuel des données comme instance de votre type de données, et met à jour les données de manière transactionnelle en une opération atomique de lecture-écriture-modification. Tout le code du bloc updateData est traité comme une seule transaction.

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 }
    }
}

Utiliser DataStore dans une application Compose

Pour utiliser DataStore dans une application Compose, suivez les consignes d'architecture des applications Android en conservant les opérations DataStore dans votre couche de données (par exemple, un dépôt) et en exposant les données à votre interface utilisateur via un ViewModel.

Évitez de lire ou d'écrire directement dans DataStore au sein de vos fonctions composables.

1. Exposez DataStore via un ViewModel. Transmettez votre dépôt (qui encapsule DataStore) à votre ViewModel et convertissez le Flow en StateFlow afin que l'interface utilisateur puisse l'observer facilement, comme illustré dans l'extrait de code suivant :

   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. Observez et écrivez à partir de votre composable. Utilisez collectAsStateWithLifecycle pour observer en toute sécurité le StateFlow dans votre interface utilisateur, et appelez les fonctions ViewModel pour gérer les écritures, comme illustré dans l'extrait de code suivant :

   @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")
           }
       }
   }
   

Utiliser DataStore dans un code multiprocessus

Vous pouvez configurer DataStore pour accéder aux mêmes données dans différents processus avec les mêmes propriétés de cohérence des données que dans un seul processus. En particulier, DataStore fournit les propriétés suivantes :

• les lectures ne renvoient que les données qui ont été conservées sur le disque ;
• la lecture après écriture est cohérente ;
• les écritures sont sérialisées ;
• les lectures ne sont jamais bloquées par les écritures.

Prenons l'exemple d'une application avec un service et une activité où le service s'exécute dans un processus distinct et met régulièrement à jour le DataStore.

Cet exemple utilise un JSON DataStore, mais vous pouvez également utiliser un Preferences ou un Proto DataStore.

@Serializable
data class Time(
    val lastUpdateMillis: Long
)

Un sérialiseur indique à DataStore comment lire et écrire votre type de données. Assurez-vous d'inclure une valeur par défaut à utiliser pour le sérialiseur si aucun fichier n'a encore été créé. Voici un exemple d'implémentation utilisant 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()
        )
    }
}

Pour utiliser DataStore dans différents processus, vous devez construire l'objet DataStore à l'aide de MultiProcessDataStoreFactory pour le code de l'application et du service :

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

Ajoutez le code suivant à votre AndroidManifiest.xml :

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

Le service appelle régulièrement updateLastUpdateTime, qui écrit dans le datastore à l'aide de updateData.

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

L'application lit la valeur écrite par le service à l'aide du flux de données :

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

Nous pouvons maintenant regrouper toutes ces fonctions dans une classe appelée MultiProcessDataStore et l'utiliser dans une application.

Voici le code du service :

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()
    }
}

Et le code de l'application :

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)
    }
}

Vous pouvez utiliser Hilt l'injection de dépendances pour que votre instance DataStore soit unique pour chaque processus :

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

Gérer la corruption de fichiers

Dans de rares cas, le fichier persistant sur disque de DataStore peut être corrompu. Par défaut, DataStore ne récupère pas automatiquement les données corrompues, et les tentatives de lecture entraînent la génération d'une CorruptionException par le système.

DataStore propose une API de gestion de la corruption qui peut vous aider à récupérer les données en douceur dans un tel scénario et à éviter de générer l'exception. Lorsqu'il est configuré, le gestionnaire de corruption remplace le fichier corrompu par un nouveau fichier contenant une valeur par défaut prédéfinie.

Pour configurer ce gestionnaire, fournissez un corruptionHandler lors de la création de l'instance DataStore dans by dataStore ou dans la méthode d'usine DataStoreFactory :

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

Envoyer des commentaires

Faites-nous part de vos commentaires et de vos idées via les ressources suivantes :

Outil de suivi des problèmes :

Signalez les problèmes pour que nous puissions corriger les bugs.

Ressources supplémentaires

Pour en savoir plus sur Jetpack DataStore, consultez les ressources supplémentaires suivantes :

Exemples

Blogs

• Stocker des données avec Jetpack DataStore, de préférence

Ateliers de programmation

• Utiliser Preferences DataStore
• Travailler avec Proto DataStore