DataStore

asynchroniczne, spójne i transakcyjne przechowywanie danych, co eliminuje niektóre wady SharedPreferences;
Ostatnia aktualizacja Wersja stabilna Wersja kandydująca Wersja Beta Wersja alfa
15 stycznia 2025 r. 1.1.2 - - -

Deklarowanie zależności

Aby dodać zależność od DataStore, musisz dodać repozytorium Google Maven do projektu. Więcej informacji znajdziesz w repozytorium Maven firmy Google.

Istnieją 2 implementacje DataStore: Preferences i Proto. Wybierz jeden z tych elementów. Do każdej implementacji możesz też dodać zależności nieobsługujące Androida.

Dodaj zależności dla implementacji, której potrzebujesz, w pliku build.gradle aplikacji lub modułu:

Magazyn danych preferencji

Groovy

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

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

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

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

Kotlin

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

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

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

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

Proto DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

Opinia

Twoja opinia pomoże nam ulepszyć Jetpacka. Daj nam znać, jeśli zauważysz nowe problemy lub masz pomysły na ulepszenie tej biblioteki. Zanim utworzysz nowy problem, zapoznaj się z dotychczasowymi problemami w tej bibliotece. Możesz zagłosować na istniejący problem, klikając przycisk z gwiazdką.

Tworzenie nowego zgłoszenia

Więcej informacji znajdziesz w dokumentacji narzędzia Issue Tracker.

Wersja 1.1

Wersja 1.1.2

15 stycznia 2025 r.

androidx.datastore:datastore-*:1.1.2 został zwolniony. Wersja 1.1.2 zawiera te komitowane zmiany.

Poprawki błędów

  • Zmniejszenie opóźnienia odczytu z ciepłej pamięci (DataStore.data.first()) o 8 razy. (22b8a40)
  • ReplaceFileCorruptionHandler można utworzyć na podstawie kodu wspólnego KMP. (7632e839)

Wersja 1.1.1

1 maja 2024 r.

androidx.datastore:datastore-*:1.1.1 został zwolniony. Wersja 1.1.1 zawiera te komitowane zmiany.

Poprawki błędów

  • Zmniejszono liczbę fałszywych alarmów w Linuxie w przypadku błędu „Wystąpiłby impas zasobów”. W wyjątkowym przypadku, gdy wiele instancji DataStore próbuje zapisać dane z różnych procesów, z tego błędu zrezygnowano, odpuszczając blokadę pliku.

Wersja 1.1.0

17 kwietnia 2024 r.

androidx.datastore:datastore-*:1.1.0 został zwolniony. Wersja 1.1.0 zawiera te komity.

Główne zmiany od wersji 1.0.0

Aby dowiedzieć się więcej, zapoznaj się z informacjami o wersji 1.1.0 w wersjach alfa i beta. Oto niektóre z głównych zmian w wersji 1.1.0:

  • DataStore obsługuje teraz wiele procesów uzyskujących dostęp do tego samego pliku, z obsługą obserwowalności w różnych procesach.
  • Nowy interfejs Storage umożliwia dostosowanie sposobu przechowywania i serializacji modeli danych.
  • Teraz możesz używać DataStore w projektach Kotlin Multiplatform.

Wersja 1.1.0-rc01

3 kwietnia 2024 r.

androidx.datastore:datastore-*:1.1.0-rc01 został zwolniony. Wersja 1.1.0-rc01 zawiera te komity.

Poprawki błędów

  • Usunięto problem z obniżeniem wydajności, który występował, gdy wywołania updateData nie optymalizowały zapisów na dysku, jeśli nowe dane były takie same jak stare (d64cfb5)
  • Rozwiązano problem z warunkiem wyścigu, w którym funkcja MultiProcess DataStore mogła pominąć unieważnienia podczas inicjalizacji. ((b/326141553),(094c2dd))

Wersja 1.1.0-beta02

6 marca 2024 roku

androidx.datastore:datastore-*:1.1.0-beta02 został zwolniony. Wersja 1.1.0-beta02 zawiera te komity.

Poprawki błędów

  • Ulepszenie wydajności w DataStore zbiera powiadomienia o aktualizacjach tylko wtedy, gdy jest to obserwowane. (b/267792241)
    • Jeśli używasz biblioteki testowania Coroutines, ta zmiana może wywołać błąd UncompletedCoroutinesError w testach. Aby uniknąć tego problemu, podczas inicjowania DataStore w testach podaj wartość TestScope.backgroundScope.
  • Rozwiązaliśmy problem z zablokowaniem się zagnieżdżonych wywołań updateData w tej samej instancji. (b/241760537)
  • Funkcja DataStore nie powoduje już błędu IOExceptions, jeśli nie można usunąć elementu SharedPreferences podczas migracji. (b/195553816)
  • Rozwiązaliśmy problem, który powodował niepowodzenie operacji zmiany nazwy pliku podczas updateData w środowiskach JVM innych niż Android. (b/203087070)
  • Rozwiązaliśmy problem polegający na tym, że CorruptionException nie jest obsługiwany po inicjalizacji DataStore. (b/289582516)

Wersja 1.1.0-beta01

10 stycznia 2024 r.

androidx.datastore:datastore-*:1.1.0-beta01 jest publikowany bez zmian od 1.1.0-alpha07. Wersja 1.1.0-beta01 zawiera te commity.

Wersja 1.1.0-alpha07

29 listopada 2023 r.

androidx.datastore:datastore-*:1.1.0-alpha07 został zwolniony. Wersja 1.1.0-alpha07 zawiera te commity.

Zmiany w interfejsie API

  • Metody MultiProcessDataStoreFactory nie są już eksperymentalne.Adnotacja @ExperimentalMultiProcessDataStore została całkowicie usunięta. (Ieee54, I8e607)

Poprawki błędów

  • Wdrożenie usunięcia adnotacji @ExperimentalMultiProcessDataStore w wersji 1.1.0-alpha07. (I8e607)

Wersja 1.1.0-alpha06

1 listopada 2023 roku

androidx.datastore:datastore-*:1.1.0-alpha06 został zwolniony. Wersja 1.1.0-alpha06 zawiera te commity.

Zmiany w interfejsie API

  • Metoda fabryki createSingleProcessCoordinator otrzymuje teraz ścieżkę do pliku (String, java.io.File i okio.Path), aby była zgodna z metodą createMultiProcessCoordinator. (I211c8, b/305755935)

Wersja 1.1.0-alpha05

6 września 2023 r.

androidx.datastore:datastore-*:1.1.0-alpha05 został zwolniony. Wersja 1.1.0-alpha05 zawiera te commity.

Zmiany w interfejsie API

  • Datastore FileStorage jest teraz dostępny publicznie, więc klienci mogą podawać parametry niestandardowe. (Icb985)
  • Zmieniono konstruktor OkioStorage tak, aby przyjmował parametr InterProcessCoordinator, dzięki czemu można go używać na Androidzie z MultiProcessCoordinator. (Iecea3)

Poprawki błędów

  • Rozwiązanie: MultiProcessCoordinator nie można monitorować wielu plików w tym samym katalogu.
  • Rozwiązanie problemu polegające na tym, że nie można wykryć plików, które się powtarzają, jeśli ścieżki do plików nie są znormalizowane.
  • Napraw nieprawidłowe wartości zwracane przez funkcję RxDataStore#isDisposed.
  • Napraw brak konfiguracji Proguarda dla artefaktu datstore-preferences-core.

Wersja 1.1.0-alpha04

5 kwietnia 2023 r.

androidx.datastore:datastore-*:1.1.0-alpha04 został zwolniony. Wersja 1.1.0-alpha04 zawiera te commity.

Poprawki błędów

  • Ulepszona implementacja wewnętrzna, która zapobiega sytuacji, w której przepływ danych DataStore może po aktualizacji emitować starszą wartość.

Wersja 1.1.0-alpha03

24 marca 2023 r.

androidx.datastore:datastore-*:1.1.0-alpha03 został zwolniony.

Poprawki błędów

  • Usunięto ograniczenia zależności z artefaktów Maven, aby obejść problem z tworzeniem w Kotlin Native Targets (b/274786186, KT-57531).

Wersja 1.1.0-alpha02

22 marca 2023 r.

androidx.datastore:datastore-*:1.1.0-alpha02 został zwolniony. Wersja 1.1.0-alpha02 zawiera te commity.

Uwaga

Ta wersja zawiera ważną wewnętrzną zmianę, która łączy implementacje DataStore dla pojedynczego procesu i wielu procesów. Obserwuj możliwe niezamierzone zmiany w zachowaniu (np. czas wyświetlania powiadomień o aktualizacjach). Aby zgłosić takie zmiany, możesz użyć komponentu śledzenia problemów.

Nowe funkcje

  • Możesz teraz używać DataStore w projektach KMM. Pamiętaj, że wersje DataStore na platformy inne niż Android są nadal eksperymentalne, ale postanowiliśmy połączyć wersje, aby ułatwić deweloperom ich wypróbowanie.
  • Funkcje wieloprocesowe zostały przeniesione z androidx.datastore.multiprocess do androidx.datastore.core.
  • Dodaj nową metodę fabryczną w androidx.datastore.core.MultiProcessDataStoreFactory, aby tworzyć instancje DataStore za pomocą obiektów Storage na potrzeby operacji na plikach.
  • Dodaliśmy nowy interfejs InterProcessCoordinator, który ułatwia komunikację między wieloma instancjami DataStore w ramach procesów. Pamiętaj, że implementacja InterProcessCoordinator w wielu procesach jest dostępna tylko na Androidzie.

Zmiany w interfejsie API

  • Dodawanie InterProcessCoordinator do StorageConnection w interfejsie datastore-core (I555bb)
  • Zmień interfejsy API w bibliotece MultiProcessDataStoreFactory, aby używać Storage. (Iac02f)
  • Przenoszenie publicznych interfejsów API z datastore-multiprocess do datastore-core (I76d7c)
  • Wyeksponowano PreferencesSerializer z datastore-preferences-core (I4b788).
  • Dodawanie adnotacji @JvmDefaultWithCompatibility (I8f206)

Wersja 1.1.0-alpha01

9 listopada 2022 r.

androidx.datastore:datastore-*:1.1.0-alpha01 został zwolniony. Wersja 1.1.0-alpha01 zawiera te commity.

Nowe funkcje

  • Obsługa przypadków użycia z wieloma procesami, w których spójność danych jest gwarantowana w DataStore instancjach w różnych procesach. Dodaj MultiProcessDataStoreFactory#create, aby utworzyć takie instancje DataStore.
  • Nowy interfejs miejsca na dane, który umożliwia przełączanie mechanizmu podstawowego miejsca na dane dla usługi Datastore. Dostępne są implementacje dla java.io i okio. Fabryki DataStore mają nowe metody, które akceptują ten obiekt Storage.

Zmiany w interfejsie API

  • Zmień interfejsy API w bibliotece MultiProcessDataStoreFactory, aby korzystać z Storage. (Iac02f)
  • Przenoszenie publicznych interfejsów API z datastore-multiprocess do datastore-core (I76d7c)
  • Wyeksponowano PreferencesSerializer z datastore-preferences-core (I4b788).

Wersja 1.0.0

Wersja 1.0.0

4 sierpnia 2021 r.

androidx.datastore:datastore-*:1.0.0 został zwolniony. Wersja 1.0.0 zawiera te zatwierdzenia.

Najważniejsze funkcje wersji 1.0.0

Jetpack DataStore to rozwiązanie do przechowywania danych, które umożliwia przechowywanie par klucz-wartość lub typowanych obiektów za pomocą buforów protokołów. DataStore używa coroutines i Flow w języku Kotlin do asynchronicznego, spójnego i transakcyjnego przechowywania danych.

Wersja 1.0.0-rc02

21 lipca 2021 r.

androidx.datastore:datastore-*:1.0.0-rc02 został zwolniony. Wersja 1.0.0-rc02 zawiera te zatwierdzenia.

Poprawki błędów

  • Wyjaśnij, że funkcja SharedPreferencesMigration nie działa, jeśli nie ma kluczy. (Icfa32, b/192824325)
  • Usunięto błąd, który powodował, że funkcja SharedPreferencesMigration utworzona za pomocą funkcji MIGRATE_ALL_KEYS wyrzucała wyjątek, jeśli żądany klucz jeszcze nie istniał. (Ie318a, b/192824325)

Wersja 1.0.0-rc01

30 czerwca 2021 r.

androidx.datastore:datastore-*:1.0.0-rc01 został zwolniony. Wersja 1.0.0-rc01 zawiera te zatwierdzenia.

Poprawki błędów

  • Rozwiązano błąd, który powodował, że plik .java został przypadkowo dodany do ostatecznego pliku jar (I65d96, b/188985637).

Wersja 1.0.0-beta02

16 czerwca 2021 r.

androidx.datastore:datastore-*:1.0.0-beta02 został zwolniony. Wersja 1.0.0-beta02 zawiera te zatwierdzenia.

Poprawki błędów

  • Rozwiązanie problemu ClassVerificationFailure (b/187450483)

Wersja 1.0.0-beta01

21 kwietnia 2021 r.

androidx.datastore:datastore-*:1.0.0-beta01 został zwolniony. Wersja 1.0.0-beta01 zawiera te commity.

Zmiany w interfejsie API

  • Usuń przeciążenia JVM dla metod tylko w języku Kotlin (I2adc7)

Poprawki błędów

  • Naprawiono błąd, który powodował wyciek kontekstów w przypadku delegowania zadań do bazy danych (Ie96fc, b/184415662).

Wersja 1.0.0-alpha08

10 marca 2021 r.

androidx.datastore:datastore-*:1.0.0-alpha08 został zwolniony. Wersja 1.0.0-alpha08 zawiera te zatwierdzenia.

Zmiany w interfejsie API

  • Teraz możesz dodać migrację, która zależy od kontekstu, do delegata usługi dataStore i preferencesDataStore. (I4ef69, b/173726702)
  • Dodaje funkcje pomocnicze do pobierania nazwy pliku, jeśli nie używasz już delegata bazy danych ani funkcji context.createDataStore (I60f9a).
  • Serializer writeTo i readFrom są teraz zawieszone. Jeśli masz zaimplementowany serializator, musisz zaktualizować swoje funkcje, aby były to funkcje zawieszania. (I1e58e)
  • Dodano obiekty zastępcze dla użytkowników RxDataStore. (Ied768, b/173726702)

Poprawki błędów

  • Wprowadzanie ograniczeń dotyczących publicznego używania eksperymentalnych interfejsów API (I6aa29, b/174531520)

Wersja 1.0.0-alpha07

24 lutego 2021 r.

androidx.datastore:datastore-*:1.0.0-alpha07 został zwolniony. Wersja 1.0.0-alpha07 zawiera te commity.

Zmiany w interfejsie API

  • Funkcja rozszerzenia Context.createDataStore została usunięta i zastąpiona delegatem właściwości globalDataStore. Zawołaj globalDataStore raz na najwyższym poziomie w pliku kotlin. Przykład:

    val Context.myDataStore by dataStore(...)

    Umieść go na najwyższym poziomie pliku kotlin, aby istniał tylko jeden jego egzemplarz. (I57215, b/173726702)

  • Funkcje RxDataStore są teraz dostępne w klasie RxDataStore, a nie w funkcjach rozszerzenia w klasie DataStore. (Idccdb, b/177691248)

  • Jeśli chcesz przenieść EncryptedSharedPreferences (lub bezpośrednie dane SharedPreferences) do DataStore, możesz to zrobić za pomocą nowego konstruktora SharedPreferencesMigration, który umożliwia wstrzyknięcie SharedPreferences. (I8e04e, b/177278510)

Poprawki błędów

  • Jeśli w przypadku tego samego pliku jest więcej aktywnych obiektów DataStore, wywoływany będzie wyjątek. Jeśli nie zarządzasz DataStore jako elementu Singleton lub nie dbasz o to, aby nie było jednocześnie aktywnych 2 instancji DataStore dla jednego pliku, możesz teraz zobaczyć wyjątki podczas odczytu lub zapisu do DataStore. Można je rozwiązać, zarządzając DataStore jako Singletonem. (Ib43f4, b/177691248)
  • Poprawka zachowania anulowania, gdy zakres rozmówcy został anulowany. (I2c7b3)

Wersja 1.0.0-alpha06

13 stycznia 2021 r.

androidx.datastore:datastore-*:1.0.0-alpha06 został zwolniony. Wersja 1.0.0-alpha06 zawiera te commity.

Nowe funkcje

  • Dodano owijacze RxJava dla DataStore. Elementy datastore-rxjava2/3 zawierają obudowy dla podstawowych interfejsów DataStore API (RxDataStore, RxDataStoreBuilder i RxDataMigration). Elementy datastore-preferences-rxjava2/3 zawierają konstruktor do tworzenia interfejsu DataStore preferencji.

Zmiany w interfejsie API

  • Ukryj interfejs CorruptionHandler. Nie było powodu, aby był on publiczny, ponieważ fabryka DataStore akceptuje tylko ReplaceFileCorruptionHandler. (I0b3b3, b/176032264)
  • Metoda preferencesKey<T>(name: String): Key<T> została usunięta i zastąpiona metodami specyficznymi dla każdego obsługiwanego typu. Na przykład preferencesKey<Int>("int") to teraz intPreferencesKey("int") (Ibcfac, b/170311106).

Poprawki błędów

  • Poprawiono dokumentację klasy DataStoreFactory, w której nie uwzględniono faktu, że plik bazy danych jest tworzony w podkatalogu „datastore/”. (Ica222)

Wersja 1.0.0-alpha05

2 grudnia 2020 r.

androidx.datastore:datastore-*:1.0.0-alpha05 został zwolniony. Wersja 1.0.0-alpha05 zawiera te commity.

Poprawki błędów

  • Dodanie lepszej dokumentacji i wyjątków dotyczących jednoczesnych zapisów z baz danych. (Ia98a2, b/173522155, b/173726702)
  • Teraz zezwalamy (ale nie wymagamy) zamykania OutputStream przekazanego do Serializer.writeTo(). (I5c9bf, b/173037611)

Wersja 1.0.0-alpha04

17 listopada 2020 r.

androidx.datastore:datastore-*:1.0.0-alpha04 został zwolniony. Wersja 1.0.0-alpha04 zawiera te commity.

Poprawki błędów

  • Rozwiązano problem z pakowaniem, który powodował następujący błąd w bazie danych preferencji 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Wersja 1.0.0-alpha03

11 listopada 2020 roku

androidx.datastore:datastore-*:1.0.0-alpha03 został zwolniony. Wersja 1.0.0-alpha03 zawiera te commity.

Nowe funkcje

  • Ustawienia obsługują teraz wartości podwójne (co jest przydatne, jeśli potrzebujesz większej precyzji niż liczby zmiennoprzecinkowe) (I5be8f, b/169471808)

Zmiany w interfejsie API

  • Utworzono czystą zależność Kotlina od Datastore, aby umożliwić szybszą kompilację. androidx.datastore:datastore-core zawiera podstawowe interfejsy API tylko dla Kotlina, a androidx.datastore:datastore zawiera interfejsy API zależne od Androida (w tym konstruktor SharedPreferencesMigration i Context.createDataStore). (I42d75, b/168512698)
  • Wyodrębnienie celów dla magazynu danych preferencji w celu przyspieszenia kompilacji Kotlina (Ia3c19)

  • Serwery serializujące wymagają teraz nowej właściwości dla wartości domyślnej, która będzie używana, jeśli na dysku nie ma danych. Ułatwia to implementację niestandardowych serializatorów, dzięki czemu użytkownicy nie muszą traktować inaczej pustych strumieni wejściowych (puste strumienie wejściowe nie są analizowane za pomocą json).

    • Dodano też sprawdzanie, czy strumień wyjściowy przekazany do metody writeTo() nie jest zamknięty. Jeśli tak, to zgłaszane są wyjątki (I16e29).

  • Uczynienie konstruktora SharedPreferencesView wewnętrznym. Początkowo była publiczna, aby umożliwić testowanie. Testy powinny zamiast tego tworzyć obiekt SharedPreferencesMigration i na jego podstawie przeprowadzać testy. (I93891)

Poprawki błędów

  • Parametr produceFile w funkcjach DataStoreFactory i PreferenceDataStoreFactory jest teraz ostatnim parametrem na liście, co umożliwia użycie składni funkcji lambda na końcu w języku Kotlin. (Ibe7f1, b/169425442)
  • Postępowanie zgodnie z nowymi wymaganiami dotyczącymi interfejsu API w przypadku Kotlina (I5ae1e)

Znane problemy

  • Magazyn danych z preferencjami ulega awarii w przypadku java.lang.NoClassDefFoundError. (b/173036843)

Wersja 1.0.0-alpha02

14 października 2020 r.

androidx.datastore:datastore-core:1.0.0-alpha02 i androidx.datastore:datastore-preferences:1.0.0-alpha02 są dostępne. Wersja 1.0.0-alpha02 zawiera te commity.

Poprawki błędów

  • Dodano zabezpieczenie przed mutacją w datastore-core. Mutacja powoduje przerwanie korzystania z magazynu danych przez osoby korzystające z magazynu danych z typami innymi niż proto czy preferencje (I6aa84)
  • Dodano metodę toString do pliku Preferences.kt, aby ułatwić debugowanie bieżącego stanu (I96006).
  • Dodano wyjątek, aby chronić przed niewłaściwym użyciem DataStore.Preferences (I1134d)
  • Usunięto błąd powodujący awarię aplikacji podczas uruchamiania (I69237, b/168580258).

Wersja 1.0.0-alpha01

2 września 2020 r.

androidx.datastore:datastore-core:1.0.0-alpha01 i androidx.datastore:datastore-preferences:1.0.0-alpha01 są dostępne. Wersja 1.0.0-alpha01 zawiera te commity.

Nowe funkcje

Jetpack DataStore to nowe i ulepszone rozwiązanie do przechowywania danych, które ma zastąpić SharedPreferences. Biblioteka DataStore korzysta z co-routines i Flow w Kotlinie, a dzięki temu oferuje 2 różne implementacje:

  • Proto DataStore, który umożliwia przechowywanie typowanych obiektów (obsługiwanych przez bufory protokołów).
  • preferencji, który przechowuje pary klucz-wartość;

Dane są przechowywane asynchronicznie, spójnie i transakcyjnie, co eliminuje większość wad SharedPreferences.