Datastore

Archivia i dati in modo asincrono, coerente e transazionale, superando alcuni degli svantaggi di SharedPreferences
Aggiornamento più recente Release stabile Candidato per la release Versione beta Release alpha
20 marzo 2024 1.0.0 1.1.0-rc01 - -

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. Facci sapere se rilevi nuovi problemi o hai idee per migliorare la libreria. Dai un'occhiata ai problemi esistenti in questa libreria prima di crearne una nuova. 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-beta02

6 marzo 2024

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

Correzioni di bug

  • Il miglioramento delle prestazioni su DataStore raccoglie notifiche di aggiornamento solo quando viene osservato. (b/267792241)
    • Tieni presente che questa modifica potrebbe attivare UncompletedCoroutinesError nei tuoi test se utilizzi la libreria di test di Coroutines. Per evitare questo problema, assicurati di superare l'TestScope.backgroundScope durante l'inizializzazione di DataStore nei tuoi test.
  • Risolto il problema delle chiamate updateData nidificate sulla stessa istanza che generava un deadlock. (b/241760537)
  • DataStore non genera più IOExceptions se non riesce a eliminare SharedPreferences durante la migrazione. (b/195553816)
  • Risolto il problema per cui la ridenominazione dei file non va a buon fine durante updateData in ambienti JVM non Android. (b/203087070)
  • Risolto il problema per cui CorruptionException non viene gestito dopo l'inizializzazione di DataStore. (b/289582516)

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

  • Datastore FileStorage è ora disponibile pubblicamente, quindi i client possono fornire parametri personalizzati. (Icb985)
  • Il costruttore OkioStorage è stato modificato per accettare un InterProcessCoordinator in modo che possa essere utilizzato su Android con MultiProcessCoordinator. (Iecea3)

Correzioni di bug

  • Risoluzione dell'errore MultiProcessCoordinator che non riesce a monitorare più file nella stessa directory.
  • Correzione non riuscita a rilevare i file duplicati se i percorsi dei file non sono normalizzati.
  • Correggi i valori errati restituiti da RxDataStore#isDisposed.
  • Correggi la configurazione ProGuard mancante per datstore-preferences-core artefatto.

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 precedente 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 al comportamento, ad esempio 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 di DataStore sono ancora sperimentali, ma abbiamo deciso di unire le versioni per consentire agli sviluppatori di provarle più facilmente.
  • Le funzionalità con più processi 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 consente a più istanze DataStore di comunicare tra processi. Tieni presente che l'implementazione multiprocesso di InterProcessCoordinator è disponibile solo su Android.

Modifiche alle API

  • Aggiungi InterProcessCoordinator a StorageConnection nell'interfaccia del datastore-core (I555bb)
  • Modifica le API nel core del datastore MultiProcessDataStoreFactory per utilizzare Storage. (Iac02f)
  • Sposta le API pubbliche in datastore-multiprocess in datastore-core (I76d7c)
  • 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 multiprocesso in cui la coerenza dei dati è garantita tra DataStore istanze nei vari processi. Aggiungi MultiProcessDataStoreFactory#create per creare queste istanze DataStore.
  • Nuova interfaccia di archiviazione che consente di scollegare il meccanismo di archiviazione sottostante per Datastore. Sono incluse le implementazioni per java.io e okio. DataStore fabbriche hanno nuovi metodi che accettano questo oggetto Storage.

Modifiche alle API

  • Modifica le API nel core del datastore MultiProcessDataStoreFactory per utilizzare Storage. (Iac02f)
  • Sposta le API pubbliche in datastore-multiprocess in datastore-core (I76d7c)
  • 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 le 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 se non sono presenti chiavi. (Icfa32, b/192824325).
  • Correggi il bug in cui l'elemento 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 veniva 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 i sovraccarichi JVM per i 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 al delegato della tua 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, dovrai aggiornare le funzioni per sospenderle. (I1e58e).
  • Aggiunti delegati proprietà per gli utenti RxDataStore. (Ied768, b/173726702)

Correzioni di bug

  • Applicare restrizioni all'uso 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 ne esista una sola. (I57215, b/173726702)

  • Le funzioni di 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) a 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 gestisci il tuo DataStore come Singleton o non ti assicuri che non ci siano due istanze di DataStore 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à

  • Sono stati aggiunti wrapper RxJava per 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 builder per creare un datastore delle preferenze.

Modifiche alle API

  • Nascondi l'interfaccia di CorruptionHandler. Non esisteva alcun motivo per renderlo pubblico perché il data di fabbrica del 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 DataStoreManufacturer, che tralascia il fatto che il file del datastore è stato 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 sulle 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 Preference 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 i valori doppi (opzione utile se hai bisogno di maggiore precisione rispetto ai valori 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 principali di Kotlin, 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 kotlin più rapida (Ia3c19)
  • I serializzatori ora richiedono una nuova proprietà per il valore predefinito che verrà utilizzato se non ci sono dati sul disco. In questo modo è più facile implementare i serializzatori personalizzati in modo che gli utenti non debbano fare flussi di input vuoti in casi speciali (stream di input vuoti non vengono analizzati con il formato json).

    • Ora è disponibile anche un controllo per confermare che il flusso di output fornito a writeTo() non sia chiuso e che, se chiuso, genera delle eccezioni (I16e29).
  • Creazione del costruttore per SharedPreferencesView all'interno. Originariamente era pubblico per consentire i test. I test dovrebbero creare un oggetto SharedPreferences Migration 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).
  • In seguito ai nuovi requisiti espliciti per le 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 di tipo non proto/senza preferenze (I6aa84)
  • È stato aggiunto un metodo toString a preferenze.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 soluzione di archiviazione dei dati nuova e 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 DataStore, che memorizza le coppie chiave-valore

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