DataStore Część pakietu Android Jetpack.
Jetpack DataStore to rozwiązanie do przechowywania danych, które umożliwia przechowywanie par klucz-wartość lub obiektów wpisanych za pomocą buforów protokołów. DataStore wykorzystuje współprogramy Kotlin i Flow do przechowywania danych asynchronicznie, spójnie i transakcyjnie.
Jeśli do przechowywania danych używasz obecnie SharedPreferences
, rozważ migrację do DataStore.
Preferencje DataStore i Proto DataStore
DataStore udostępnia 2 różne implementacje: Preferences DataStore i Proto DataStore.
- Preferencje DataStore przechowuje i uzyskuje dostęp do danych za pomocą kluczy. Ta implementacja nie wymaga wstępnie zdefiniowanego schematu i nie zapewnia bezpieczeństwa typu.
- Proto DataStore przechowuje dane jako wystąpienia niestandardowego typu danych. Ta implementacja wymaga zdefiniowania schematu za pomocą buforów protokołów, ale zapewnia bezpieczeństwo typu.
Odpowiednie korzystanie z DataStore
Aby móc prawidłowo korzystać z DataStore, pamiętaj o tych regułach:
Nigdy nie twórz więcej niż 1 instancji elementu
DataStore
dla danego pliku w ramach tego samego procesu. Może to uniemożliwić działanie wszystkich funkcji DataStore. Jeśli dla danego pliku jest aktywnych wiele magazynów danych w tym samym procesie, DataStore zwróci żądanieIllegalStateException
podczas odczytywania lub aktualizowania danych.Ogólny typ magazynu danych
musi być stały. Muszanie typu używanego w DataStore unieważnia wszelkie gwarancje udzielane przez DataStore i tworzy potencjalnie poważne, trudne do wychwycenia błędy. Zdecydowanie zalecamy korzystanie z buforów protokołów, które zapewniają gwarancje niezmienności, prosty interfejs API i wydajną serializację.Nigdy nie łącz przypadki użycia
SingleProcessDataStore
iMultiProcessDataStore
w tym samym pliku. Jeśli chcesz uzyskać dostęp do usługiDataStore
w więcej niż jednym procesie, zawsze używaj narzędziaMultiProcessDataStore
.
Skonfiguruj
Aby użyć Jetpack DataStore w swojej aplikacji, dodaj ten kod do pliku Gradle w zależności od implementacji, której chcesz użyć:
Preferencje (DataStore)
Odlotowy
// 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
Odlotowy
// 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") }
Przechowuj pary klucz-wartość w usłudze Preferences DataStore
Implementacja magazynu danych preferencji używa klas DataStore
i Preferences
do utrwalania prostych par klucz-wartość na dysku.
Tworzenie magazynu danych preferencji
Aby utworzyć instancję Datastore<Preferences>
, użyj delegata usługi utworzonej przez użytkownika preferencesDataStore
. Wywołaj je raz na najwyższym poziomie pliku kotlin i uzyskaj do niego dostęp za pośrednictwem tej właściwości w pozostałej części aplikacji. Dzięki temu łatwiej będzie utrzymać urządzenie DataStore
jako pojedyncze. Jeśli używasz RxJava, możesz też użyć polecenia RxPreferenceDataStoreBuilder
. Obowiązkowy parametr name
to nazwa preferencji w DataStore.
Kotlin
// At the top level of your kotlin file: val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")
Java
RxDataStore<Preferences> dataStore = new RxPreferenceDataStoreBuilder(context, /*name=*/ "settings").build();
Odczyt z magazynu danych preferencji
Ustawienia DataStore nie korzysta ze wstępnie zdefiniowanego schematu, więc musisz użyć odpowiedniej funkcji typu klucza, aby zdefiniować klucz dla każdej wartości, którą chcesz przechowywać w instancji DataStore<Preferences>
. Aby np. zdefiniować klucz dla wartości całkowitej, użyj intPreferencesKey()
.
Następnie użyj właściwości DataStore.data
, aby udostępnić odpowiednią wartość zapisaną w elemencie Flow
.
Kotlin
val EXAMPLE_COUNTER = intPreferencesKey("example_counter") val exampleCounterFlow: Flow<Int> = context.dataStore.data .map { preferences -> // No type safety. preferences[EXAMPLE_COUNTER] ?: 0 }
Java
Preferences.Key<Integer> EXAMPLE_COUNTER = PreferencesKeys.int("example_counter"); Flowable<Integer> exampleCounterFlow = dataStore.data().map(prefs -> prefs.get(EXAMPLE_COUNTER));
Zapisywanie w magazynie danych preferencji
Preferencje w DataStore udostępnia funkcję edit()
, która przeprowadza transakcyjną aktualizację danych w elemencie DataStore
. Parametr transform
funkcji akceptuje blok kodu, w którym możesz aktualizować wartości w razie potrzeby. Cały kod w bloku przekształcenia jest traktowany jako jedna transakcja.
Kotlin
suspend fun incrementCounter() { context.dataStore.edit { settings -> val currentCounterValue = settings[EXAMPLE_COUNTER] ?: 0 settings[EXAMPLE_COUNTER] = currentCounterValue + 1 } }
Java
Single<Preferences> updateResult = dataStore.updateDataAsync(prefsIn -> { MutablePreferences mutablePreferences = prefsIn.toMutablePreferences(); Integer currentInt = prefsIn.get(INTEGER_KEY); mutablePreferences.set(INTEGER_KEY, currentInt != null ? currentInt + 1 : 1); return Single.just(mutablePreferences); }); // The update is completed once updateResult is completed.
Przechowywanie obiektów typów za pomocą Proto DataStore
Implementacja Proto DataStore korzysta z DataStore i buforów protokołów do utrwalania wpisanych obiektów na dysku.
Zdefiniuj schemat
Proto DataStore wymaga wstępnie zdefiniowanego schematu w pliku protokołu w katalogu app/src/main/proto/
. Ten schemat określa typ obiektów, które przechowujesz w Proto DataStore. Więcej informacji o definiowaniu schematu proto znajdziesz w przewodniku po języku protobuf.
syntax = "proto3";
option java_package = "com.example.application";
option java_multiple_files = true;
message Settings {
int32 example_counter = 1;
}
Tworzenie Proto DataStore
Tworzenie magazynu danych Proto do przechowywania obiektów typów składa się z 2 kroków:
- Zdefiniuj klasę, która implementuje funkcję
Serializer<T>
, gdzieT
to typ zdefiniowany w pliku proto. Ta klasa serializatora informuje DataStore o tym, jak odczytywać i zapisywać typ danych. Jeśli nie masz jeszcze utworzonego pliku, pamiętaj o podaniu wartości domyślnej serializatora, który ma być używany. - Użyj delegata właściwości utworzonego przez
dataStore
, aby utworzyć wystąpienieDataStore<T>
, gdzieT
to typ zdefiniowany w pliku proto. Wywołaj je na najwyższym poziomie pliku kotlin i uzyskaj dostęp do niego za pomocą tej usługi, która przekazuje dostęp do pozostałych części aplikacji. Parametrfilename
wskazuje, który plik ma być używany do przechowywania danych, a parametrserializer
informuje DataStore o nazwie klasy serializatora zdefiniowanej w kroku 1.
Kotlin
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) = t.writeTo(output) } val Context.settingsDataStore: DataStore<Settings> by dataStore( fileName = "settings.pb", serializer = SettingsSerializer )
Java
private static class SettingsSerializer implements Serializer<Settings> { @Override public Settings getDefaultValue() { Settings.getDefaultInstance(); } @Override public Settings readFrom(@NotNull InputStream input) { try { return Settings.parseFrom(input); } catch (exception: InvalidProtocolBufferException) { throw CorruptionException(“Cannot read proto.”, exception); } } @Override public void writeTo(Settings t, @NotNull OutputStream output) { t.writeTo(output); } } RxDataStore<Byte> dataStore = new RxDataStoreBuilder<Byte>(context, /* fileName= */ "settings.pb", new SettingsSerializer()).build();
Odczytywanie z Proto DataStore
Użyj narzędzia DataStore.data
, aby udostępnić Flow
odpowiedniej właściwości z przechowywanego obiektu.
Kotlin
val exampleCounterFlow: Flow<Int> = context.settingsDataStore.data .map { settings -> // The exampleCounter property is generated from the proto schema. settings.exampleCounter }
Java
Flowable<Integer> exampleCounterFlow = dataStore.data().map(settings -> settings.getExampleCounter());
Zapisz w Proto DataStore
Proto DataStore udostępnia funkcję updateData()
, która przeprowadza transakcyjną aktualizację zapisanego obiektu. Funkcja updateData()
podaje bieżący stan danych jako instancję typu danych i aktualizuje dane transakcyjnie w niepodzielnej operacji odczytu, zapisu i modyfikowania.
Kotlin
suspend fun incrementCounter() { context.settingsDataStore.updateData { currentSettings -> currentSettings.toBuilder() .setExampleCounter(currentSettings.exampleCounter + 1) .build() } }
Java
Single<Settings> updateResult = dataStore.updateDataAsync(currentSettings -> Single.just( currentSettings.toBuilder() .setExampleCounter(currentSettings.getExampleCounter() + 1) .build()));
Używanie DataStore w kodzie synchronicznym
Jedną z głównych zalet DataStore jest asynchroniczny interfejs API, ale zmiana otaczającego kodu na asynchroniczny może nie zawsze być możliwa. Może się tak zdarzyć, jeśli pracujesz z istniejącą bazą kodu, która korzysta z synchronicznego wejścia-wyjścia dysku, lub korzystasz z zależności, która nie zapewnia asynchronicznego interfejsu API.
współprogramy Kotlin udostępniają konstruktor współprogramów runBlocking()
, który pomaga wypełnić lukę między kodem synchronicznym i asynchronicznym. Za pomocą runBlocking()
możesz synchronicznie odczytywać dane z DataStore.
RxJava oferuje metody blokowania w witrynie Flowable
. Ten kod blokuje wątek wywołujący, dopóki DataStore nie zwróci danych:
Kotlin
val exampleData = runBlocking { context.dataStore.data.first() }
Java
Settings settings = dataStore.data().blockingFirst();
Wykonywanie synchronicznych operacji wejścia-wyjścia w wątku UI może powodować błędy ANR i zacinanie się interfejsu. Możesz rozwiązać te problemy, asynchroniczne wstępne wczytywanie danych z DataStore:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { lifecycleScope.launch { context.dataStore.data.first() // You should also handle IOExceptions here. } }
Java
dataStore.data().first().subscribe();
Dzięki temu DataStore asynchronicznie odczytuje dane i zapisuje je w pamięci podręcznej. Późniejsze odczyty synchroniczne z użyciem funkcji runBlocking()
mogą być szybsze lub mogą całkowicie uniknąć operacji wejścia-wyjścia dysku po zakończeniu wstępnego odczytu.
Używanie DataStore w kodzie wieloprocesowym
Możesz skonfigurować DataStore tak, aby uzyskać dostęp do tych samych danych w różnych procesach z takimi samymi gwarancjami spójności danych jak w przypadku jednego procesu. W szczególności DataStore gwarantuje:
- Odczyty zwracają tylko dane, które zostały zapisane na dysku.
- Spójność odczytu po zapisie.
- Zapisy są zserializowane.
- Zapisy nigdy nie są blokowane przez odczyty.
Rozważmy przykładową aplikację z usługą i działaniem:
Usługa działa w osobnym procesie i okresowo aktualizuje magazyn danych
<service android:name=".MyService" android:process=":my_process_id" />
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int { scope.launch { while(isActive) { dataStore.updateData { Settings(lastUpdate = System.currentTimeMillis()) } delay(1000) } } }
Aplikacja zbiera te zmiany i aktualizuje swój interfejs
val settings: Settings by dataStore.data.collectAsState() Text( text = "Last updated: $${settings.timestamp}", )
Aby móc używać DataStore w różnych procesach, musisz utworzyć obiekt DataStore za pomocą MultiProcessDataStoreFactory
.
val dataStore: DataStore<Settings> = MultiProcessDataStoreFactory.create(
serializer = SettingsSerializer(),
produceFile = {
File("${context.cacheDir.path}/myapp.preferences_pb")
}
)
serializer
informuje DataStore, jak odczytywać i zapisywać typ danych.
Jeśli nie utworzono jeszcze pliku, pamiętaj o podaniu domyślnej wartości serializatora, który ma być używany. Poniżej znajduje się przykład użycia funkcji kotlinx.serialization:
@Serializable
data class Settings(
val lastUpdate: Long
)
@Singleton
class SettingsSerializer @Inject constructor() : Serializer<Settings> {
override val defaultValue = Settings(lastUpdate = 0)
override suspend fun readFrom(input: InputStream): Timer =
try {
Json.decodeFromString(
Settings.serializer(), 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(Settings.serializer(), t)
.encodeToByteArray()
)
}
}
Możesz użyć wstrzykiwania zależności Hilt, aby upewnić się, że instancja DataStore jest unikalna w ramach każdego procesu:
@Provides
@Singleton
fun provideDataStore(@ApplicationContext context: Context): DataStore<Settings> =
MultiProcessDataStoreFactory.create(...)
Prześlij opinię
Podziel się z nami swoją opinią i pomysłami, korzystając z tych zasobów:
- Śledzenie problemów
- Zgłoś problemy, żebyśmy mogli naprawić błędy.
Dodatkowe materiały
Aby dowiedzieć się więcej o Jetpack DataStore, zobacz te dodatkowe materiały:
Próbki
Blogi
Ćwiczenia z programowania
Polecane dla Ciebie
- Uwaga: tekst linku jest wyświetlany, gdy JavaScript jest wyłączony
- Wczytywanie i wyświetlanie danych z podziałem na strony
- Omówienie LiveData
- Układy i wyrażenia powiązania