Datastore

Archivia i dati in modo asincrono, coerente e transazionale, superando alcuni degli svantaggi di SharedPreferences
Aggiornamento più recente Release stabile Candidato di rilascio Versione beta Versione alpha
10 gennaio 2024 1.0.0 - 1.1.0-beta01 -

Dichiarazione delle dipendenze

Per aggiungere una dipendenza a DataStore, devi aggiungere il Repository Maven di Google al tuo progetto. Per ulteriori informazioni, consulta il Repository Maven di Google.

Esistono due implementazioni di DataStore: Preferenze e Proto. Scegli l'una o l'altra opzione. Puoi anche aggiungere dipendenze senza Android a entrambe le implementazioni.

Aggiungi le dipendenze per l'implementazione di cui hai bisogno nel file build.gradle per l'app o il modulo:

Preferenze di Datastore

Trendy

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

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.0.0"

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

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.0.0"
    }
    

Kotlin

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

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.0.0")

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

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.0.0")
    }
    

Datastore di protocollo

Trendy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.0.0"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.0.0"

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

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.0.0"
    }
    

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.0.0")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.0.0")

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

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.0.0")
    }
    

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Contattaci se scopri nuovi problemi o hai idee per migliorare la libreria. Dai un'occhiata ai problemi esistenti in questa libreria prima di crearne uno nuovo. Puoi aggiungere il tuo voto a un problema esistente facendo clic sul pulsante a forma di stella.

Crea un nuovo problema

Per ulteriori informazioni, consulta la documentazione di Issue Tracker.

Versione 1.1

Versione 1.1.0-beta01

10 gennaio 2024

androidx.datastore:datastore-*:1.1.0-beta01 viene rilasciato senza modifiche dal giorno 1.1.0-alpha07. La versione 1.1.0-beta01 contiene questi commit.

Versione 1.1.0-alpha07

29 novembre 2023

androidx.datastore:datastore-*:1.1.0-alpha07 viene rilasciato. La versione 1.1.0-alpha07 contiene questi commit.

Modifiche alle API

  • I metodi MultiProcessDataStoreFactory non sono più sperimentali.L'annotazione @ExperimentalMultiProcessDataStore è stata rimossa completamente. (Ieee54, I8e607)

Correzioni di bug

  • Implementa la rimozione delle annotazioni @ExperimentalMultiProcessDataStore alla versione 1.1.0-alpha07. (I8e607)

Versione 1.1.0-alpha06

1° novembre 2023

androidx.datastore:datastore-*:1.1.0-alpha06 viene rilasciato. La versione 1.1.0-alpha06 contiene questi commit.

Modifiche alle API

  • Il metodo di fabbrica createSingleProcessCoordinator ora riceve un percorso file (String, java.io.File e okio.Path) per essere coerente con createMultiProcessCoordinator. (I211c8, b/305755935)

Versione 1.1.0-alpha05

6 settembre 2023

androidx.datastore:datastore-*:1.1.0-alpha05 viene rilasciato. La versione 1.1.0-alpha05 contiene questi commit.

Modifiche alle API

  • Il datastore FileStorage è ora disponibile pubblicamente, quindi i client possono fornire parametri personalizzati. (Icb985)
  • È stato cambiato il costruttore OkioStorage in modo che accetti un InterProcessCoordinator per poterlo utilizzare su Android con MultiProcessCoordinator. (Iecea3)

Correzioni di bug

  • Risolvi il problema MultiProcessCoordinator che non è riuscito a monitorare più file nella stessa directory.
  • Correzione dell'impossibilità di rilevare file duplicati se i percorsi dei file non sono normalizzati.
  • Correggi i valori errati restituiti da RxDataStore#isDisposed.
  • Correggi la configurazione ProGuard mancante per l'artefatto datstore-preferences-core.

Versione 1.1.0-alpha04

5 aprile 2023

androidx.datastore:datastore-*:1.1.0-alpha04 viene rilasciato. La versione 1.1.0-alpha04 contiene questi commit.

Correzioni di bug

  • Migliora l'implementazione interna per evitare una condizione di gara in cui il flusso di dati di DataStore potrebbe emettere un valore meno recente dopo un aggiornamento.

Versione 1.1.0-alpha03

24 marzo 2023

androidx.datastore:datastore-*:1.1.0-alpha03 viene rilasciato.

Correzioni di bug

  • Rimossi i vincoli di dipendenza dagli artefatti Maven per risolvere un problema di build nelle destinazioni native di Kotlin (b/274786186, KT-57531).

Versione 1.1.0-alpha02

22 marzo 2023

androidx.datastore:datastore-*:1.1.0-alpha02 viene rilasciato. La versione 1.1.0-alpha02 contiene questi commit.

Nota

Tieni presente che questa versione include un importante refactoring interno che unisce le implementazioni per le implementazioni a processo singolo e multiprocesso DataStore. Tieni d'occhio eventuali modifiche indesiderate del comportamento (ad es. le tempistiche delle notifiche relative agli aggiornamenti). Puoi utilizzare il componente Issue Tracker per segnalare queste modifiche.

Nuove funzionalità

  • Ora puoi utilizzare DataStore nei progetti KMM. Tieni presente che i target non Android del DataStore sono ancora sperimentali, ma abbiamo deciso di unire le versioni per consentire agli sviluppatori di provarle più facilmente.
  • Le funzionalità multiprocesso sono state spostate da androidx.datastore.multiprocess a androidx.datastore.core.
  • Aggiungi un nuovo metodo di fabbrica in androidx.datastore.core.MultiProcessDataStoreFactory per creare istanze DataStore con oggetti Storage per le operazioni con i file.
  • Aggiungi una nuova interfaccia InterProcessCoordinator che aiuta più istanze di DataStore a comunicare tra i processi. Tieni presente che l'implementazione multiprocesso di InterProcessCoordinator è disponibile solo su Android.

Modifiche alle API

  • Aggiunta di InterProcessCoordinator a StorageConnection nell'interfaccia principale del datastore (I555bb)
  • Modifica le API nell'MultiProcessDataStoreFactory principale del datastore per utilizzare Storage. (Iac02f)
  • Sposta le API pubbliche da datastore-multiprocess a datastore-core (I76d7c)
  • Valore PreferencesSerializer esposto da datastore-preferences-core (I4b788)
  • Aggiunta dell'annotazione @JvmDefaultWithCompatibility (I8f206)

Versione 1.1.0-alpha01

9 novembre 2022

androidx.datastore:datastore-*:1.1.0-alpha01 viene rilasciato. La versione 1.1.0-alpha01 contiene questi commit.

Nuove funzionalità

  • Supporta casi d'uso multi-processo in cui è garantita la coerenza dei dati tra DataStore istanze nei vari processi. Aggiungi MultiProcessDataStoreFactory#create per creare queste istanze DataStore.
  • Nuova interfaccia di Storage che consente la sostituzione del meccanismo di archiviazione sottostante per Datastore. Sono fornite le implementazioni per java.io e okio. DataStore fabbriche hanno nuovi metodi che accettano questo oggetto Storage.

Modifiche alle API

  • Modifica le API nell'MultiProcessDataStoreFactory principale del datastore per utilizzare Storage. (Iac02f)
  • Sposta le API pubbliche da datastore-multiprocess a datastore-core (I76d7c)
  • Valore PreferencesSerializer esposto da datastore-preferences-core (I4b788)

Versione 1.0.0

Versione 1.0.0

4 agosto 2021

androidx.datastore:datastore-*:1.0.0 viene rilasciato. La versione 1.0.0 contiene questi commit.

Funzionalità principali della versione 1.0.0

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

Versione 1.0.0-rc02

21 luglio 2021

androidx.datastore:datastore-*:1.0.0-rc02 viene rilasciato. La versione 1.0.0-rc02 contiene questi commit.

Correzioni di bug

  • Chiarisci che SharedPreferencesMigration non viene eseguito in assenza di chiavi. (Icfa32, b/192824325)
  • È stato risolto il bug in cui SharedPreferencesMigration creato con MIGRATE_ALL_KEYS generava un'eccezione se la chiave richiesta non esiste ancora. (Ie318a, b/192824325)

Versione 1.0.0-rc01

30 giugno 2021

androidx.datastore:datastore-*:1.0.0-rc01 viene rilasciato. La versione 1.0.0-rc01 contiene questi commit.

Correzioni di bug

  • Corregge il bug per cui il file .java è stato inavvertitamente aggiunto nel jar finale (I65d96, b/188985637)

Versione 1.0.0-beta02

16 giugno 2021

androidx.datastore:datastore-*:1.0.0-beta02 viene rilasciato. La versione 1.0.0-beta02 contiene questi commit.

Correzioni di bug

Versione 1.0.0-beta01

21 aprile 2021

androidx.datastore:datastore-*:1.0.0-beta01 viene rilasciato. La versione 1.0.0-beta01 contiene questi commit.

Modifiche alle API

  • Rimuovi sovraccarichi JVM per metodi solo kotlin (I2adc7)

Correzioni di bug

  • Risolto un bug per cui i delegati del datastore potrebbero comportare la perdita di contesti (Ie96fc, b/184415662)

Versione 1.0.0-alpha08

10 marzo 2021

androidx.datastore:datastore-*:1.0.0-alpha08 viene rilasciato. La versione 1.0.0-alpha08 contiene questi commit.

Modifiche alle API

  • Ora puoi aggiungere una migrazione che dipende dal contesto alla persona delegata per la proprietà dataStore e preferencesDataStore. (I4ef69, b/173726702)
  • Aggiunge funzioni helper per ottenere il nome del file se non utilizzi più delegato datastore o context.createDataStore (I60f9a)
  • I serializzatori writeTo e readFrom sono in fase di sospensione. Se hai implementato un serializzatore, per sospenderle devi aggiornare le funzioni. (I1e58e)
  • Aggiunti delegati della proprietà per gli utenti RxDataStore. (Ied768, b/173726702)

Correzioni di bug

  • Applicare restrizioni all'utilizzo pubblico delle API sperimentali (I6aa29, b/174531520)

Versione 1.0.0-alpha07

24 febbraio 2021

androidx.datastore:datastore-*:1.0.0-alpha07 viene rilasciato. La versione 1.0.0-alpha07 contiene questi commit.

Modifiche alle API

  • La funzione dell'estensione Context.createDataStore è stata rimossa e sostituita con il delegato della proprietà globalDataStore. Chiama globalDataStore una volta al livello superiore nel file Kotlin. Ecco alcuni esempi:

    val Context.myDataStore by dataStore(...)
    

    Posizionalo al livello superiore del file kotlin in modo che ci sia una sola istanza. (I57215, b/173726702)

  • Le funzioni RxDataStore ora si trovano in una classe RxDataStore anziché in funzioni di estensione su DataStore. (Idccdb, b/177691248)

  • Se vuoi eseguire la migrazione di EncryptedSharedPreferences (o di avvio diretto SharedPreferences) in DataStore, ora puoi farlo con il nuovo costruttore SharedPreferences Migration, che ti consente di inserire SharedPreferences. (I8e04e, b/177278510)

Correzioni di bug

  • DataStore ora genererà un'eccezione se sono presenti più datastore attivi per lo stesso file. Se non gestivi il tuo DataStore come singleton o non ti stavi assicurando che due istanze di DataStore non siano attive contemporaneamente per un file, ora potresti vedere delle eccezioni durante la lettura o la scrittura in DataStore. Questi problemi possono essere risolti gestendo il tuo DataStore come singleton. (Ib43f4, b/177691248)
  • Correggi il comportamento di annullamento quando l'ambito del chiamante viene annullato. (I2c7b3)

Versione 1.0.0-alpha06

13 gennaio 2021

androidx.datastore:datastore-*:1.0.0-alpha06 viene rilasciato. La versione 1.0.0-alpha06 contiene questi commit.

Nuove funzionalità

  • Aggiunti wrapper RxJava per il DataStore. Gli artefatti datastore-rxjava2/3 contengono i wrapper per le API DataStore principali (RxDataStore, RxDataStoreBuilder e RxDataMigration). Gli artefatti datastore-preferences-rxjava2/3 contengono un generatore per creare un datastore delle preferenze.

Modifiche alle API

  • Nascondi l'interfaccia di CorruptionHandler. Non c'era motivo per essere pubblico, perché il fabbrica di DataStore accetta solo un DetectFileCorruptionHandler. (I0b3b3, b/176032264)
  • Il metodo preferencesKey<T>(name: String): Key<T> è stato rimosso e sostituito con metodi specifici per ogni tipo supportato, ad esempio preferencesKey<Int>("int") è ora intPreferencesKey("int") (Ibcfac, b/170311106)

Correzioni di bug

  • Corregge la documentazione su DataStoreFactory che tralasciava il fatto che il file del datastore viene creato nella sottodirectory "datastore/". (Ica222)

Versione 1.0.0-alpha05

2 dicembre 2020

androidx.datastore:datastore-*:1.0.0-alpha05 viene rilasciato. La versione 1.0.0-alpha05 contiene questi commit.

Correzioni di bug

  • Aggiungi una documentazione migliore ed eccezioni relative alle scritture simultanee dai datastore. (Ia98a2, b/173522155, b/173726702)
  • Ora consentiamo (ma non è necessario) la chiusura dell'outputStream passato a Serializer.writeTo(). (I5c9bf, b/173037611)

Versione 1.0.0-alpha04

17 novembre 2020

androidx.datastore:datastore-*:1.0.0-alpha04 viene rilasciato. La versione 1.0.0-alpha04 contiene questi commit.

Correzioni di bug

  • Risolto un problema di pacchettizzazione che causa il seguente arresto anomalo in Datastore 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Versione 1.0.0-alpha03

11 novembre 2020

androidx.datastore:datastore-*:1.0.0-alpha03 viene rilasciato. La versione 1.0.0-alpha03 contiene questi commit.

Nuove funzionalità

  • Le preferenze ora supportano valori doppi, il che è utile se hai bisogno di maggiore precisione rispetto ai numeri in virgola mobile (I5be8f, b/169471808)

Modifiche alle API

  • È stata creata una dipendenza kotlin pura per il datastore per consentire una compilazione più rapida. androidx.datastore:datastore-core contiene solo le API kotlin principali, mentre androidx.datastore:datastore contiene le API che dipendono da Android (inclusi SharedPreferencesMigration e il costruttore Context.createDataStore). (I42d75, b/168512698)
  • Suddivisione dei target per il datastore delle preferenze per una compilazione più veloce del kotlin (Ia3c19)
  • I serializzatori ora richiedono una nuova proprietà per il valore predefinito che verrà utilizzato se non ci sono dati sul disco. Ciò semplifica l'implementazione di serializzatori personalizzati in modo che gli utenti non debbano eseguire flussi di input vuoti in casi speciali (stream di input vuoti non vengono analizzati con il formato json).

    • Inoltre, è disponibile un controllo per confermare che il flusso di output fornito a writeTo() non sia chiuso e, se è chiuso, genera delle eccezioni (I16e29).
  • Utilizzo del costruttore per SharedPreferencesView all'interno. Inizialmente era pubblico per consentire i test. I test dovrebbero invece creare un oggetto SharedPreferencesMigrate e testarlo. (I93891)

Correzioni di bug

  • Il parametro produceFile su DataStoreFactory e PreferenceDataStoreFactory è ora l'ultimo parametro dell'elenco, quindi ti consente di utilizzare la sintassi lambda finale kotlin. (Ibe7f1, b/169425442)
  • A seguito dei nuovi requisiti espliciti dell'API per kotlin (I5ae1e)

Problemi noti

  • Preferenza agli arresti anomali di Datastore con java.lang.NoClassDefFoundError. (b/173036843)

Versione 1.0.0-alpha02

14 ottobre 2020

androidx.datastore:datastore-core:1.0.0-alpha02 e androidx.datastore:datastore-preferences:1.0.0-alpha02 vengono rilasciati. La versione 1.0.0-alpha02 contiene questi commit.

Correzioni di bug

  • È stata aggiunta una protezione contro le mutazioni nel core del datastore. La mutazione interrompe l'utilizzo del datastore per le persone che utilizzano un datastore con tipi non proto/non-preferences (I6aa84)
  • Aggiunto un metodo toString a Preferences.kt per semplificare il debug dello stato corrente (I96006)
  • È stata aggiunta un'eccezione per la salvaguardia dall'uso improprio di DataStore.Preferences (I1134d)
  • Risolto un bug che causava l'arresto anomalo dell'app all'avvio (I69237, b/168580258)

Versione 1.0.0-alpha01

2 settembre 2020

androidx.datastore:datastore-core:1.0.0-alpha01 e androidx.datastore:datastore-preferences:1.0.0-alpha01 vengono rilasciati. La versione 1.0.0-alpha01 contiene questi commit.

Nuove funzionalità

Jetpack DataStore è una nuova soluzione di archiviazione dati migliorata che mira a sostituire SharedPreferences. Basato sulle coroutine Kotlin e Flow, DataStore offre due diverse implementazioni:

  • Proto DataStore, che consente di archiviare oggetti digitati (supportati da buffer di protocollo)
  • Preferenze di DataStore, che memorizza le coppie chiave-valore

I dati vengono archiviati in modo asincrono, coerentemente e transazionale, superando la maggior parte degli svantaggi di SharedPreferences.