Datastore

Archivia i dati in modo asincrono, coerente e transazionale, superando alcuni degli svantaggi di SharedPreferences
Aggiornamento più recente Release stabile Candidato per l'uscita Versione beta Release alpha
1° maggio 2024 1.1.1 - - -

Dichiarazione delle dipendenze

Per aggiungere una dipendenza a Datastore, devi aggiungere il Repository Maven di Google al tuo progetto. Consulta il Repository Maven di Google per ulteriori informazioni.

Esistono due implementazioni di Datastore: Preferenze e protocollo. Scegli l'una o l'altra opzione. Puoi anche aggiungere dipendenze senza Android implementazione.

Aggiungi le dipendenze per l'implementazione necessaria nel file build.gradle per la tua app o il tuo modulo:

Preferences DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

Proto DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Non esitare a contattarci in caso di nuovi problemi o idee per migliorare questa raccolta. Dai un'occhiata alle problemi esistenti in questa raccolta, prima di crearne uno nuovo. Puoi aggiungere il tuo voto a un problema esistente tramite facendo clic sul pulsante a forma di stella.

Crea un nuovo numero

Consulta la documentazione di Issue Tracker per ulteriori informazioni.

Versione 1.1

Versione 1.1.1

1° maggio 2024

Viene rilasciato androidx.datastore:datastore-*:1.1.1. La versione 1.1.1 contiene questi commit.

Correzioni di bug

  • Falso allarme mitigato di Linux su "Si verificherà un deadlock delle risorse" in un caso d'angolo più istanze DataStore tentano di scrivere da processi diversi annullando il blocco dei file.

Versione 1.1.0

17 aprile 2024

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

Modifiche principali dalla release 1.0.0

Per ulteriori informazioni, consulta le note di rilascio delle versioni alpha e beta della versione 1.1.0. Alcuni dei principali aggiornamenti della versione 1.1.0 sono:

  • DataStore ora supporta più processi che accedono allo stesso file, con supporto per l'osservabilità tra i processi.
  • La nuova interfaccia di Storage consente di personalizzare le modalità di archiviazione o serializzazione dei modelli dei dati.
  • Ora puoi utilizzare DataStore nei progetti multipiattaforma Kotlin.

Versione 1.1.0-rc01

3 aprile 2024

Viene rilasciato androidx.datastore:datastore-*:1.1.0-rc01. La versione 1.1.0-rc01 contiene questi commit.

Correzioni di bug

  • È stato risolto il peggioramento delle prestazioni per cui le chiamate updateData non venivano ottimizzate nelle scritture su disco se i nuovi dati corrispondono a quelli precedenti (d64cfb5)
  • È stata corretta una condizione di gara per cui MultiProcess DataStore potrebbe non includere invalidazioni durante l'inizializzazione. ((b/326141553),(094c2dd))

Versione 1.1.0-beta02

6 marzo 2024

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

Correzioni di bug

  • Il miglioramento delle prestazioni in DataStore raccoglie le notifiche di aggiornamento solo quando vengono osservate. (b/267792241)
      .
    • Tieni presente che questa modifica potrebbe attivare UncompletedCoroutinesError nei tuoi test se utilizzi la libreria di test Coroutines. Assicurati di superare TestScope.backgroundScope durante l'inizializzazione di DataStore nei test per evitare questo problema.
  • È stato risolto il problema del deadlock delle chiamate updateData nidificate nella stessa istanza. (b/241760537)
  • DataStore impostato non restituisce più IOExceptions se non riesce a eliminare SharedPreferences durante la migrazione. (b/195553816)
  • È stato risolto il problema per cui la ridenominazione dei file non va a buon fine durante updateData in ambienti JVM non Android. (b/203087070)
  • È stato 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

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

Modifiche alle API

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

Correzioni di bug

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

Versione 1.1.0-alpha06

1° novembre 2023

Viene rilasciato androidx.datastore:datastore-*:1.1.0-alpha06. 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 coerenza con createMultiProcessCoordinator. (I211c8, b/305755935)

Versione 1.1.0-alpha05

6 settembre 2023

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

Modifiche alle API

  • Datastore FileStorage è ora disponibile pubblicamente, quindi i clienti possono fornire parametri personalizzati. (Icb985)
  • Il costruttore OkioStorage è stato modificato per accettare un InterProcessCoordinator in modo da poterlo utilizzare su Android con MultiProcessCoordinator. (Iecea3)

Correzioni di bug

  • Correggi l'impossibilità di monitorare più file nella stessa directory in MultiProcessCoordinator.
  • 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 di ProGuard mancante per datstore-preferences-core artefatto.

Versione 1.1.0-alpha04

5 aprile 2023

Viene rilasciato androidx.datastore:datastore-*:1.1.0-alpha04. 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

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

Correzioni di bug

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

Versione 1.1.0-alpha02

22 marzo 2023

Viene rilasciato androidx.datastore:datastore-*:1.1.0-alpha02. 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 di datastore a processo singolo e multiprocesso. Tieni d'occhio le possibili modifiche indesiderate del comportamento (ad es. le tempistiche delle notifiche degli 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à multi-processo vengono spostate da androidx.datastore.multiprocess a androidx.datastore.core.
  • Aggiungi un nuovo metodo di ripristino 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 i processi. Tieni presente che l'implementazione multi-processo di InterProcessCoordinator è disponibile solo su Android.

Modifiche alle API

  • Aggiungi InterProcessCoordinator a StorageConnection nell'interfaccia datastore-core (I555bb)
  • Cambia le API in MultiProcessDataStoreFactory datastore-core per utilizzare Storage. (Iac02f)
  • Spostamento delle API pubbliche da datastore-multiprocess a datastore-core (I76d7c)
  • PreferencesSerializer esposto da datastore-preferences-core (I4b788)
  • Aggiunta dell'annotazione @JvmDefaultWithCompatibility (I8f206)

Versione 1.1.0-alpha01

9 novembre 2022

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

Nuove funzionalità

  • Supporta casi d'uso multi-processo 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 la disattivazione del meccanismo di archiviazione sottostante per Datastore. Vengono fornite implementazioni per java.io e okio. DataStore fabbriche hanno nuovi metodi che accettano questo oggetto Storage.

Modifiche alle API

  • Cambia le API in MultiProcessDataStoreFactory datastore-core per utilizzare Storage. (Iac02f)
  • Spostamento delle API pubbliche da datastore-multiprocess a datastore-core (I76d7c)
  • PreferencesSerializer esposto da datastore-preferences-core (I4b788)

Versione 1.0.0

Versione 1.0.0

4 agosto 2021

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

Funzionalità principali di 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

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

Correzioni di bug

  • Chiarisci che SharedPreferencesMigration non viene eseguito se non esistono chiavi. (Icfa32, b/192824325)
  • È stato corretto il bug per 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

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

Correzioni di bug

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

Versione 1.0.0-beta02

16 giugno 2021

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

Correzioni di bug

Versione 1.0.0-beta01

21 aprile 2021

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

Modifiche alle API

  • Rimuovi i sovraccarichi della JVM per i metodi solo Kotlin (I2adc7)

Correzioni di bug

  • È stato corretto un bug per cui i delegati del datastore potevano causare fughe di contesti (Ie96fc, b/184415662)

Versione 1.0.0-alpha08

10 marzo 2021

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

Modifiche alle API

  • Ora puoi aggiungere al delegato della proprietà dataStore e preferencesDataStore una migrazione che dipende dal contesto. (I4ef69, b/173726702)
  • Aggiunge funzioni helper per ottenere il nome del file se non utilizzi più datastore delegato o context.createDataStore (I60f9a)
  • Le funzionalità writeTo e readFrom del serializzatore sono ora sospese. Se hai implementato un serializzatore, dovrai aggiornare le tue funzioni in modo che diventino funzioni di sospensione. (I1e58e).
  • Delegati di proprietà aggiunti per gli utenti RxDataStore. (Ied768, b/173726702)

Correzioni di bug

  • Applicare restrizioni sull'uso pubblico delle API sperimentali (I6aa29, b/174531520)

Versione 1.0.0-alpha07

24 febbraio 2021

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

Modifiche alle API

  • La funzione di estensione Context.createDataStore è stata rimossa e sostituita con il delegato della proprietà globalDataStore. Chiama globalDataStore una volta al livello più alto nel tuo file Kotlin. Ad esempio:

    val Context.myDataStore by dataStore(...)

    Colloca questo comando all'inizio del file Kotlin in modo che ci sia una sola istanza. (I57215, b/173726702)

  • Le funzioni RxDataStore sono ora in una classe RxDataStore anziché 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 SharedPreferencesMigrazione, che ti consente di inserire SharedPreferences. (I8e04e, b/177278510)

Correzioni di bug

  • Datastore genera un'eccezione se esistono più datastore attivi per lo stesso file. Se non gestisci il datastore come singleton o non hai garantito che non ci siano due istanze di datastore attive contemporaneamente per un file, ora potresti vedere delle eccezioni durante la lettura o la scrittura nel datastore. Questi possono essere risolti gestendo il 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

Viene rilasciato androidx.datastore:datastore-*:1.0.0-alpha06. 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 preferenze.

Modifiche alle API

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

Correzioni di bug

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

Versione 1.0.0-alpha05

2 dicembre 2020

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

Correzioni di bug

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

Versione 1.0.0-alpha04

17 novembre 2020

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

Correzioni di bug

  • È stato risolto un problema di pacchetti che causa il seguente arresto anomalo in Datastore delle preferenze 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Versione 1.0.0-alpha03

11 novembre 2020

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

Nuove funzionalità

  • Le preferenze ora supportano valori doppi (utile se hai bisogno di una maggiore precisione rispetto ai valori mobili) (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 e androidx.datastore:datastore contiene le API che dipendono da Android (tra cui il costruttore SharedPreferencesMigration e Context.createDataStore)(I42d75, b/168512698)
  • Suddivisione dei target per il datastore delle preferenze per una compilazione più rapida di Kotlin (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ù semplice implementare i serializzatori personalizzati, in modo che gli utenti non debbano utilizzare flussi di input vuoti in caso speciale (i flussi di input vuoti non vengono analizzati con json).

    • Inoltre, ora è disponibile un controllo per confermare che il flusso di output fornito a writeTo() non sia chiuso e, se viene chiuso, genera delle eccezioni (I16e29).

  • Impostazione del costruttore per SharedPreferencesView in modo interno. In origine era pubblica per consentire i test. I test dovrebbero invece creare una SharedPreferencesMigration e testarla. (I93891)

Correzioni di bug

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

Problemi noti

  • Datastore Preferenze si arresta in modo anomalo con java.lang.NoClassDefFoundError. (b/173036843)

Versione 1.0.0-alpha02

14 ottobre 2020

Vengono rilasciate le versioni androidx.datastore:datastore-core:1.0.0-alpha02 e androidx.datastore:datastore-preferences:1.0.0-alpha02. La versione 1.0.0-alpha02 contiene questi commit.

Correzioni di bug

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

Versione 1.0.0-alpha01

2 settembre 2020

Vengono rilasciate le versioni androidx.datastore:datastore-core:1.0.0-alpha01 e androidx.datastore:datastore-preferences:1.0.0-alpha01. La versione 1.0.0-alpha01 contiene questi commit.

Nuove funzionalità

Jetpack DataStore è una soluzione di archiviazione 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 dai buffer di protocollo)
  • Datastore delle preferenze, in cui vengono archiviate coppie chiave-valore

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