State i Jetpack Compose

Stan w aplikacji to dowolna wartość, która może się zmieniać z upływem czasu. Jest to bardzo szeroka definicja, która obejmuje wszystko, od bazy danych Room po zmienną w klasie.

Wszystkie aplikacje na Androida wyświetlają użytkownikowi swój stan. Oto kilka przykładów stanu w aplikacjach na Androida:

  • Snackbar wyświetlany, gdy nie można nawiązać połączenia z siecią.
  • post na blogu i powiązane z nim komentarze;
  • animacji rozchodzących się fal na przyciskach, które są odtwarzane, gdy użytkownik je kliknie;
  • Naklejki, po których użytkownik może rysować na obrazie.

Jetpack Compose pomaga w określaniu, gdzie i jak przechowywać i używać stanu w aplikacji na Androida. Ten przewodnik skupia się na połączeniu między stanem a komponentami kompozycyjnymi oraz na interfejsach API, które Jetpack Compose udostępnia, aby ułatwić pracę ze stanem.

Stan i skład

Compose jest deklaratywny, więc jedynym sposobem na jego zaktualizowanie jest wywołanie tego samego komponentu z nowymi argumentami. Te argumenty reprezentują stan interfejsu. Za każdym razem, gdy stan jest aktualizowany, następuje ponowne komponowanie. W rezultacie takie elementy jak TextField nie aktualizują się automatycznie, jak to ma miejsce w przypadku widoków opartych na imperatywnym XML-u. Aby komponent uległ aktualizacji, musi otrzymać wyraźną informację o nowym stanie.

@Composable
private fun HelloContent() {
    Column(modifier = Modifier.padding(16.dp)) {
        Text(
            text = "Hello!",
            modifier = Modifier.padding(bottom = 8.dp),
            style = MaterialTheme.typography.bodyMedium
        )
        OutlinedTextField(
            value = "",
            onValueChange = { },
            label = { Text("Name") }
        )
    }
}
StateOverviewSnippets.kt

Jeśli uruchomisz ten kod i spróbujesz wpisać tekst, zobaczysz, że nic się nie dzieje. Dzieje się tak, ponieważ TextField nie aktualizuje się samo – aktualizuje się, gdy zmienia się jego parametr value. Wynika to ze sposobu, w jaki w Compose działają kompozycja i ponowna kompozycja.

Więcej informacji o początkowej kompozycji i ponownej kompozycji znajdziesz w artykule Myślenie w Compose.

Stan w funkcjach kompozycyjnych

Funkcje kompozycyjne mogą używać interfejsu API remember do przechowywania obiektu w pamięci. Wartość obliczona przez remember jest przechowywana w kompozycji podczas początkowej kompozycji, a przechowywana wartość jest zwracana podczas ponownej kompozycji. remember można używać do przechowywania zarówno obiektów zmiennych, jak i niezmiennych.

mutableStateOf tworzy obiekt observable MutableState<T>, czyli typ observable zintegrowany z czasem działania funkcji Compose.

interface MutableState<T> : State<T> {
    override var value: T
}

Wszelkie zmiany w value powodują ponowne skomponowanie wszystkich funkcji kompozycyjnych, które odczytują value.

Obiekt MutableState w funkcji kompozycyjnej można zadeklarować na 3 sposoby:

  • val mutableState = remember { mutableStateOf(default) }
  • var value by remember { mutableStateOf(default) }
  • val (value, setValue) = remember { mutableStateOf(default) }

Te deklaracje są równoważne i stanowią uproszczoną składnię dla różnych zastosowań stanu. Wybierz ten, który generuje najbardziej czytelny kod w funkcji kompozycyjnej, którą piszesz.

Składnia delegowania by wymaga tych importów:

import androidx.compose.runtime.getValue
import androidx.compose.runtime.setValue

Zapamiętaną wartość możesz wykorzystać jako parametr innych funkcji kompozycyjnych, a nawet jako logikę w instrukcjach, aby zmieniać wyświetlane funkcje kompozycyjne. Jeśli na przykład nie chcesz wyświetlać powitania, gdy nazwa jest pusta, użyj stanu w instrukcji if:

@Composable
fun HelloContent() {
    Column(modifier = Modifier.padding(16.dp)) {
        var name by remember { mutableStateOf("") }
        if (name.isNotEmpty()) {
            Text(
                text = "Hello, $name!",
                modifier = Modifier.padding(bottom = 8.dp),
                style = MaterialTheme.typography.bodyMedium
            )
        }
        OutlinedTextField(
            value = name,
            onValueChange = { name = it },
            label = { Text("Name") }
        )
    }
}
StateOverviewSnippets.kt

remember pomaga zachować stan podczas ponownego komponowania, ale nie zachowuje go podczas zmian konfiguracji. W tym celu musisz użyć rememberSaveable. rememberSaveable automatycznie zapisuje każdą wartość, którą można zapisać w Bundle. W przypadku innych wartości możesz przekazać niestandardowy obiekt zapisujący.

Inne obsługiwane typy stanu

Compose nie wymaga używania MutableState<T> do przechowywania stanu. Obsługuje inne typy obserwowane. Zanim odczytasz w Compose inny typ obserwowalny, musisz przekonwertować go na State<T>, aby komponenty kompozycyjne mogły automatycznie ponownie się komponować, gdy zmieni się stan.

Compose zawiera funkcje do tworzenia State<T> z popularnych typów obserwowalnych używanych w aplikacjach na Androida. Zanim zaczniesz korzystać z tych integracji, dodaj odpowiednie artefakty zgodnie z poniższymi instrukcjami:

  • Flow: collectAsStateWithLifecycle()

    collectAsStateWithLifecycle() zbiera wartości z Flow w sposób uwzględniający cykl życia, co pozwala aplikacji oszczędzać zasoby. Jest to ostatnia wartość wyemitowana przez funkcję Compose State. Zalecamy używanie tego interfejsu API do zbierania informacji o ścieżkach w aplikacjach na Androida.

    collectAsStateWithLifecycle()

    W pliku build.gradle wymagana jest ta zależność (powinna to być wersja 2.6.0-beta01 lub nowsza):

Kotlin

dependencies {
      ...
      implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.7")
}

Groovy

dependencies {
      ...
      implementation "androidx.lifecycle:lifecycle-runtime-compose:2.8.7"
}

  • Flow: collectAsState()

    collectAsState jest podobny do collectAsStateWithLifecycle, ponieważ również pobiera wartości z Flow i przekształca je w State Compose.

    Zamiast collectAsStateWithLifecycle, które jest przeznaczone tylko dla Androida, używaj collectAsState w przypadku kodu niezależnego od platformy.

    collectAsState nie wymaga dodatkowych zależności, ponieważ jest dostępny w compose-runtime.

  • LiveData: observeAsState()

    observeAsState() zaczyna obserwować ten LiveData i reprezentuje jego wartości za pomocą State.

    W pliku build.gradle wymagana jest ta zależność:

Kotlin

dependencies {
      ...
      implementation("androidx.compose.runtime:runtime-livedata:1.8.1")
}

Groovy

dependencies {
      ...
      implementation "androidx.compose.runtime:runtime-livedata:1.8.1"
}

Kotlin

dependencies {
      ...
      implementation("androidx.compose.runtime:runtime-rxjava2:1.8.1")
}

Groovy

dependencies {
      ...
      implementation "androidx.compose.runtime:runtime-rxjava2:1.8.1"
}

Kotlin

dependencies {
      ...
      implementation("androidx.compose.runtime:runtime-rxjava3:1.8.1")
}

Groovy

dependencies {
      ...
      implementation "androidx.compose.runtime:runtime-rxjava3:1.8.1"
}

Stanowe a bezstanowe

Funkcja kompozycyjna, która używa remember do przechowywania obiektu, tworzy stan wewnętrzny, dzięki czemu jest stanowa. HelloContent to przykład funkcji kompozycyjnej z zachowywaniem stanu, ponieważ przechowuje i modyfikuje swój stan name wewnętrznie. Może to być przydatne w sytuacjach, w których dzwoniący nie musi kontrolować stanu i może korzystać z tej funkcji bez konieczności samodzielnego zarządzania stanem. Funkcje kompozycyjne ze stanem wewnętrznym są jednak mniej wielokrotnego użytku i trudniejsze do testowania.

Bezstanowa funkcja kompozycyjna to funkcja, która nie przechowuje żadnego stanu. Łatwym sposobem na osiągnięcie stanu bezstanowego jest użycie podnoszenia stanu.

Podczas tworzenia komponentów wielokrotnego użytku często warto udostępniać zarówno wersję z zachowywaniem stanu, jak i wersję bez zachowywania stanu tego samego komponentu. Wersja stanowa jest wygodna dla wywołujących, którzy nie dbają o stan, a wersja bezstanowa jest niezbędna dla wywołujących, którzy muszą kontrolować lub podnosić stan.

Przenoszenie stanu

Przenoszenie stanu w Compose to wzorzec przenoszenia stanu do wywołującego funkcji kompozycyjnej, aby uczynić ją bezstanową. Ogólny wzorzec przenoszenia stanu w Jetpack Compose polega na zastąpieniu zmiennej stanu 2 parametrami:

  • value: T: bieżąca wartość do wyświetlenia;
  • onValueChange: (T) -> Unit:zdarzenie, które powoduje zmianę wartości, gdzie T to proponowana nowa wartość.

Nie musisz jednak ograniczać się do onValueChange. Jeśli w przypadku komponentu kompozycyjnego odpowiednie są bardziej szczegółowe zdarzenia, zdefiniuj je za pomocą wyrażeń lambda.

Stan przenoszony w ten sposób ma kilka ważnych właściwości:

  • Jedno źródło wiarygodnych danych: przenosząc stan zamiast go duplikować, zapewniamy, że istnieje tylko jedno źródło wiarygodnych danych. Pomaga to uniknąć błędów.
  • Hermetyzacja: tylko kompozycje stanowe mogą modyfikować swój stan. Jest to całkowicie wewnętrzne.
  • Możliwość udostępniania: stan przeniesiony można udostępniać wielu funkcjom kompozycyjnym. Jeśli chcesz odczytać wartość name w innym komponencie, możesz to zrobić dzięki przenoszeniu.
  • Możliwość przechwytywania: osoby dzwoniące do funkcji kompozycyjnych bezstanowych mogą zignorować lub zmodyfikować zdarzenia przed zmianą stanu.
  • Odłączone: stan kompozycji bezstanowych może być przechowywany w dowolnym miejscu. Możesz teraz na przykład przenieść name do ViewModel.

W tym przykładzie wyodrębnisz elementy name i onValueChange z elementu HelloContent i przeniesiesz je w górę drzewa do funkcji HelloScreen, która wywołuje element HelloContent.

@Composable
fun HelloScreen() {
    var name by rememberSaveable { mutableStateOf("") }

    HelloContent(name = name, onNameChange = { name = it })
}

@Composable
fun HelloContent(name: String, onNameChange: (String) -> Unit) {
    Column(modifier = Modifier.padding(16.dp)) {
        Text(
            text = "Hello, $name",
            modifier = Modifier.padding(bottom = 8.dp),
            style = MaterialTheme.typography.bodyMedium
        )
        OutlinedTextField(value = name, onValueChange = onNameChange, label = { Text("Name") })
    }
}
StateOverviewSnippets.kt

Wyodrębnienie stanu z HelloContent ułatwia zrozumienie funkcji kompozycyjnej, ponowne użycie jej w różnych sytuacjach i testowanie. HelloContent jest oddzielony od sposobu przechowywania jego stanu. Oznacza to, że jeśli zmodyfikujesz lub zastąpisz HelloScreen, nie musisz zmieniać sposobu implementacji HelloContent.

Wzorzec, w którym stan się zmniejsza, a zdarzenia rosną, nazywa się jednokierunkowym przepływem danych. W tym przypadku stan spada z HelloScreen na HelloContent, a liczba zdarzeń rośnie z HelloContent do HelloScreen. Dzięki jednokierunkowemu przepływowi danych możesz oddzielić komponenty kompozycyjne, które wyświetlają stan w interfejsie, od części aplikacji, które przechowują i zmieniają stan.

Więcej informacji znajdziesz na stronie Where to hoist state (Miejsce podniesienia stanu).

Przywracanie stanu w Compose

Interfejs rememberSaveable API działa podobnie do remember, ponieważ zachowuje stan podczas ponownego komponowania, a także podczas ponownego tworzenia aktywności lub procesu za pomocą mechanizmu zapisanego stanu instancji. Dzieje się tak na przykład po obróceniu ekranu.

Sposoby przechowywania stanu

Wszystkie typy danych dodane do Bundle są zapisywane automatycznie. Jeśli chcesz zapisać coś, czego nie można dodać do Bundle, masz kilka opcji.

Parcelize

Najprostszym rozwiązaniem jest dodanie do obiektu adnotacji @Parcelize. Obiekt staje się możliwy do przekazania i można go połączyć w pakiet. Ten kod tworzy na przykład typ danych City z możliwością przekazywania i zapisuje go w stanie.

@Parcelize
data class City(val name: String, val country: String) : Parcelable

@Composable
fun CityScreen() {
    var selectedCity = rememberSaveable {
        mutableStateOf(City("Madrid", "Spain"))
    }
}
StateOverviewSnippets.kt

MapSaver

Jeśli z jakiegoś powodu funkcja @Parcelize nie jest odpowiednia, możesz użyć funkcji mapSaver, aby zdefiniować własną regułę przekształcania obiektu w zestaw wartości, które system może zapisać w Bundle.

data class City(val name: String, val country: String)

val CitySaver = run {
    val nameKey = "Name"
    val countryKey = "Country"
    mapSaver(
        save = { mapOf(nameKey to it.name, countryKey to it.country) },
        restore = { City(it[nameKey] as String, it[countryKey] as String) }
    )
}

@Composable
fun CityScreen() {
    var selectedCity = rememberSaveable(stateSaver = CitySaver) {
        mutableStateOf(City("Madrid", "Spain"))
    }
}
StateOverviewSnippets.kt

ListSaver

Aby uniknąć konieczności definiowania kluczy mapy, możesz też użyć listSaver i użyć jego indeksów jako kluczy:

data class City(val name: String, val country: String)

val CitySaver = listSaver<City, Any>(
    save = { listOf(it.name, it.country) },
    restore = { City(it[0] as String, it[1] as String) }
)

@Composable
fun CityScreen() {
    var selectedCity = rememberSaveable(stateSaver = CitySaver) {
        mutableStateOf(City("Madrid", "Spain"))
    }
}
StateOverviewSnippets.kt

Zmienne stanu w Compose

Proste przenoszenie stanu można zarządzać w samych funkcjach kompozycyjnych. Jeśli jednak ilość stanu, który trzeba śledzić, wzrośnie lub w funkcjach kompozycyjnych pojawi się logika do wykonania, warto przekazać odpowiedzialność za logikę i stan innym klasom: obiektom przechowującym stan.

Więcej informacji znajdziesz w dokumentacji podnoszenia stanu w Compose lub na stronie Obiekty stanu i stan interfejsu w przewodniku po architekturze.

Ponowne uruchamianie obliczeń zapamiętywania po zmianie kluczy

Interfejs remember API jest często używany razem z MutableState:

var name by remember { mutableStateOf("") }
StateOverviewSnippets.kt

W tym przypadku użycie funkcji remember sprawia, że wartość MutableState przetrwa ponowne kompozycje.

Ogólnie rzecz biorąc, funkcja remember przyjmuje parametr lambda calculation. Gdy funkcja remember zostanie uruchomiona po raz pierwszy, wywoła funkcję lambda calculation i zapisze jej wynik. Podczas ponownego komponowania funkcja remember zwraca ostatnio zapisaną wartość.

Oprócz stanu buforowania możesz też używać remember do przechowywania w kompozycji dowolnego obiektu lub wyniku działania, którego inicjowanie lub obliczanie jest kosztowne. Możesz nie chcieć powtarzać tego obliczenia przy każdej ponownej kompozycji. Przykładem może być utworzenie tego obiektu ShaderBrush, które jest kosztowną operacją:

val brush = remember {
    ShaderBrush(
        BitmapShader(
            ImageBitmap.imageResource(res, avatarRes).asAndroidBitmap(),
            Shader.TileMode.REPEAT,
            Shader.TileMode.REPEAT
        )
    )
}
StateOverviewSnippets.kt

remember przechowuje wartość do momentu, gdy opuści ona kompozycję. Istnieje jednak sposób na unieważnienie wartości w pamięci podręcznej. Interfejs remember API przyjmuje też parametr key lub keys. Jeśli którykolwiek z tych kluczy ulegnie zmianie, przy następnym remember ponownym wygenerowaniu funkcji nastąpi unieważnienie pamięci podręcznej i ponowne wykonanie bloku lambda obliczeń. Ten mechanizm pozwala kontrolować czas życia obiektu w kompozycji. Obliczenia pozostają ważne do momentu zmiany danych wejściowych, a nie do momentu, gdy zapamiętana wartość opuści kompozycję.

Poniższe przykłady pokazują, jak działa ten mechanizm.

W tym fragmencie kodu tworzony jest obiekt ShaderBrush, który jest używany jako kolor tła funkcji kompozycyjnej Box. remember przechowuje instancję ShaderBrush, ponieważ jej ponowne utworzenie jest kosztowne, jak wyjaśniono wcześniej. remember przyjmuje avatarRes jako parametr key1, czyli wybrany obraz tła. Jeśli avatarRes się zmieni, pędzel ponownie skomponuje obraz i zastosuje go do Box. Może się to zdarzyć, gdy użytkownik wybierze z selektora inny obraz jako tło.

@Composable
private fun BackgroundBanner(
    @DrawableRes avatarRes: Int,
    modifier: Modifier = Modifier,
    res: Resources = LocalContext.current.resources
) {
    val brush = remember(key1 = avatarRes) {
        ShaderBrush(
            BitmapShader(
                ImageBitmap.imageResource(res, avatarRes).asAndroidBitmap(),
                Shader.TileMode.REPEAT,
                Shader.TileMode.REPEAT
            )
        )
    }

    Box(
        modifier = modifier.background(brush)
    ) {
        /* ... */
    }
}
StateOverviewSnippets.kt

W następnym fragmencie stan jest przenoszony do zwykłej klasy przechowującej stan MyAppState. Udostępnia funkcję rememberMyAppState do inicjowania instancji klasy za pomocą remember. Udostępnianie takich funkcji w celu utworzenia instancji, która przetrwa ponowne kompozycje, jest w Compose powszechnym wzorcem. Funkcja rememberMyAppState otrzymuje wartość windowSizeClass, która służy jako parametr key dla funkcji remember. Jeśli ten parametr ulegnie zmianie, aplikacja musi ponownie utworzyć klasę zwykłego stanu z najnowszą wartością. Może się tak zdarzyć, gdy np. użytkownik obróci urządzenie.

@Composable
private fun rememberMyAppState(
    windowSizeClass: WindowSizeClass
): MyAppState {
    return remember(windowSizeClass) {
        MyAppState(windowSizeClass)
    }
}

@Stable
class MyAppState(
    private val windowSizeClass: WindowSizeClass
) { /* ... */ }
StateOverviewSnippets.kt

Compose używa implementacji metody equals klasy, aby określić, czy klucz uległ zmianie, i unieważnić zapisaną wartość.

Przechowywanie stanu za pomocą kluczy poza ponownym komponowaniem

Interfejs rememberSaveable API to otoka interfejsu remember, która może przechowywać dane w Bundle. Ten interfejs API umożliwia zachowanie stanu nie tylko podczas ponownego komponowania, ale też podczas ponownego tworzenia aktywności i zakończenia procesu zainicjowanego przez system. rememberSaveable otrzymuje input parametry o tym samym celu co remember otrzymuje keys. Pamięć podręczna jest unieważniana, gdy zmieni się którykolwiek z danych wejściowych. Przy następnym ponownym skomponowaniu funkcji rememberSaveableponownie wykonarememberSaveable blok lambda obliczeń.

buforowana wartość zostanie unieważniona.

W przykładzie poniżej zmienna rememberSaveable przechowuje wartość userTypedQuery do momentu zmiany wartości typedQuery:

var userTypedQuery by rememberSaveable(typedQuery, stateSaver = TextFieldValue.Saver) {
    mutableStateOf(
        TextFieldValue(text = typedQuery, selection = TextRange(typedQuery.length))
    )
}
StateOverviewSnippets.kt

Więcej informacji

Więcej informacji o stanie i Jetpack Compose znajdziesz w tych dodatkowych materiałach.

Próbki

Codelabs

Filmy

Blogi