State i Jetpack Compose

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

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

  • pasek powiadomień, który wyświetla się, gdy nie można nawiązać połączenia sieciowego;
  • Post na blogu i powiązane komentarze.
  • Faliste animacje na przyciskach uruchamianych po kliknięciu przez użytkownika.
  • Naklejki, które użytkownik może rysować na obrazie.

Jetpack Compose pomaga określić, gdzie i jak przechowywać stan oraz jak z niego korzystać w aplikacji na Androida. Ten przewodnik skupia się na związku między stanem a komponowalnymi komponentami oraz na interfejsach API, które Jetpack Compose udostępnia, aby ułatwić pracę ze stanem.

Stan i skład

Funkcja kompozytorna jest deklaratywna, więc jedynym sposobem na jej zaktualizowanie jest wywołanie tej samej funkcji kompozytowanej z nowymi argumentami. Te argumenty są reprezentacją stanu interfejsu użytkownika. Za każdym razem, gdy stan jest aktualizowany, następuje rekompozycja. W efekcie takie elementy jak TextField nie są aktualizowane automatycznie tak jak w wymiarach XML. Aby komponent mógł się odpowiednio zaktualizować, musi być poinformowany 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, nic się nie stanie. Wynika to z tego, że TextField się nie aktualizuje, tylko aktualizują się wraz ze zmianą parametru value. Wynika to ze sposobu, w jaki działa kompozycja i rekompozycja w funkcji Compose.

Więcej informacji o pierwotnej i ponownej kompozycji znajdziesz w artykule Kompozycja – sposób myślenia.

Stan w elementach kompozycyjnych

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

mutableStateOf tworzy obserwowalny typ MutableState<T>, który jest obserwacyjnym typem zintegrowanym ze środowiskiem wykonawczym tworzenia.

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

Wszelkie zmiany w funkcji value powodują przekomponowanie wszystkich funkcji składanych, które odczytują value.

Obiekt MutableState można zadeklarować w funkcji kompozycyjnej 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 służą jako skróty składniowe do różnych zastosowań stanu. Wybierz ten, który generuje kod najłatwiejszy do odczytania w komponowalnym elemencie, który piszesz.

Składnia delegata by wymaga tych importów:

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

Zapamiętaną wartość możesz użyć jako parametru dla innych komponentów lub nawet jako logiki w oświadczeniach, aby zmienić wyświetlane komponenty. Jeśli na przykład nie chcesz wyświetlać powitania, jeśli jego 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

Funkcja remember pomaga zachować stan w przypadku rekompozycji, ale nie zachowuje stanu w przypadku zmian konfiguracji. Aby to zrobić, musisz użyć rememberSaveable. rememberSaveable automatycznie zapisuje wszystkie wartości, które można zapisać w Bundle. W przypadku innych wartości możesz przekazać obiekt wygaszacza niestandardowego.

Inne obsługiwane typy stanu

W komponowaniu nie musisz używać MutableState<T> do przechowywania stanu. Obsługuje on inne obserwowalne typy. Zanim odczytasz inny typ obserwowalny w komponencie, musisz go przekonwertować na State<T>, aby komponenty mogły się automatycznie ponownie skompilować po zmianie stanu.

Compose jest dostarczany z funkcjami umożliwiającymi tworzenie State<T> na podstawie typów obserwowalnych powszechnie używanych w aplikacjach na Androida. Zanim użyjesz tych integracji, dodaj odpowiednie elementy w sposób opisany poniżej:

  • Flow: collectAsStateWithLifecycle()

    collectAsStateWithLifecycle() zbiera wartości z Flow w sposób uwzględniający cykl życia, co pozwala aplikacji oszczędzać zasoby. Reprezentuje ostatnią wyemitowaną wartość z funkcji tworzenia wiadomości State. Używaj tego interfejsu API jako zalecanego sposobu gromadzenia przepływów w aplikacjach na Androida.

    W pliku build.gradle (powinien być w wersji 2.6.0-beta01 lub nowszej) wymagana jest ta zależność:

Kotlin

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

Groovy

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

  • Flow: collectAsState()

    Funkcja collectAsState jest podobna do funkcji collectAsStateWithLifecycle, ponieważ również zbiera wartości z elementu Flow i przekształca je w element Compose State.

    Zamiast collectAsStateWithLifecycle, który jest przeznaczony tylko na Androida, używaj kodu niezależnego od platformy (collectAsState).

    W przypadku funkcji collectAsState dodatkowe zależności nie są wymagane, ponieważ jest ono dostępne w interfejsie compose-runtime.

  • LiveData: observeAsState()

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

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

Kotlin

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

Groovy

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

Kotlin

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

Groovy

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

Kotlin

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

Groovy

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

Stanowa a bezstanowa

Funkcja kompozycyjna, która używa remember do przechowywania obiektu, tworzy stan wewnętrzny, przez co obiekt kompozycyjny jest stanowy. HelloContent jest przykładem kompozytu stanu, ponieważ przechowuje i modyfikuje stan name wewnętrznie. Może to być przydatne w sytuacjach, gdy dzwoniący nie musi kontrolować stanu i może go używać bez konieczności samodzielnego zarządzania nim. Jednak komponenty z wewnętrznym stanem są zwykle mniej wielokrotnego użytku i trudniejsze do przetestowania.

Funkcja bezstanowa kompozycyjna to funkcja kompozycyjna, która nie zachowuje żadnego stanu. Prostym sposobem na osiągnięcie stanu bezstanowego jest użycie hoistingu stanu.

Gdy tworzysz elementy kompozycyjne wielokrotnego użytku, często chcesz udostępnić zarówno stanową, jak i bezstanową wersję tego samego elementu kompozycyjnego. Wersja ze stanem jest wygodna dla wywołujących, którym stan nie jest potrzebny, a wersja bezstanowa jest niezbędna dla wywołujących, którzy muszą kontrolować stan lub go podnosić.

Przenoszenie stanu

Przenoszenie stanu w komponowalnym to wzór przenoszenia stanu do wywołującego komponentu, aby uczynić go stanem bezstanowym. Ogólnym wzorcem przenoszenia stanów w Jetpack Compose jest zastąpienie zmiennej stanu 2 parametrami:

  • value: T: bieżąca wartość do wyświetlenia
  • onValueChange: (T) -> Unit: zdarzenie żądające zmiany wartości, gdzie T to nowa wartość proponowana.

Nie musisz jednak ograniczać się do onValueChange. Jeśli dla funkcji kompozycyjnej potrzebne są bardziej szczegółowe zdarzenia, zdefiniuj je za pomocą parametrów lambda.

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

  • Jedno źródło wiarygodnych danych: przeniesienie stanu zamiast jego powielania zapewnia, że istnieje tylko jedno źródło wiarygodnych danych. Pomaga to uniknąć błędów.
  • Opakowane: stan mogą modyfikować tylko komponenty stateful. Mają charakter wewnętrzny.
  • Możliwość udostępniania: stan hostowany może być udostępniany wielu elementom składanym. Jeśli chcesz odczytać name w innej składanej, możesz to zrobić dzięki funkcji podnoszenia.
  • Intercepable: wywołujące bezstanowe funkcje kompozycyjne mogą ignorować lub modyfikować zdarzenia przed zmianą stanu.
  • Rozdzielone: stan bezstanowych komponentów może być przechowywany w dowolnym miejscu. Można na przykład przenieść name do ViewModel.

W tym przykładzie wyodrębniasz name i onValueChange z HelloContent i przenosisz je w górę do kompozycji HelloScreen, która wywołuje 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

Dzięki wyodrębnieniu stanu z poziomu HelloContent łatwiej jest analizować komponent, używać go ponownie w różnych sytuacjach i testować. Element HelloContent jest oddzielony od sposobu przechowywania stanu. Odłączenie oznacza, że jeśli zmodyfikujesz lub zastąpisz HelloScreen, nie musisz zmieniać sposobu implementacji HelloContent.

Wzór, w którym stan maleje, a liczba zdarzeń rośnie, nazywa się jednokierunkowym przepływem danych. W tym przypadku stan maleje z HelloScreen do HelloContent, a liczba zdarzeń wzrasta z HelloContent do HelloScreen. Dzięki jednokierunkowemu przepływowi danych możesz odłączyć komponenty, które wyświetlają stan w interfejsie, od części aplikacji, które przechowują i zmieniają stan.

Więcej informacji znajdziesz na stronie Gdzie przenieść stan.

Przywracanie stanu w sekcji Tworzenie

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

Sposoby zapisywania stanu

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

Parcelize

Najprostszym rozwiązaniem jest dodanie do obiektu adnotacji @Parcelize. Obiekt staje się podzielny i można go spakować. Na przykład ten kod tworzy typ danych City, który można podzielić, 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

Zapisywanie map

Jeśli z jakiegoś powodu @Parcelize nie jest odpowiedni, możesz użyć funkcji mapSaver, aby zdefiniować własną regułę konwertowania obiektu na zestaw wartości, które system może zapisać w atrybucie 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

Zapisywanie listy

Aby uniknąć konieczności definiowania kluczy mapy, możesz też użyć parametru 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 edytorze

Prostym przenoszeniem stanu można zarządzać bezpośrednio w funkcjach kompozycyjnych. Jeśli jednak ilość stanów, które należy śledzić, rośnie lub jeśli w funkcjach składanych pojawia się logika do wykonania, warto delegować logikę i odpowiedzialnie za stany innym klasom: holderom stanu.

Aby dowiedzieć się więcej, zapoznaj się z dokumentacją dotyczącą przenoszenia stanu w Compose lub ogólniej ze stroną Trzymacze stanu i stan interfejsu użytkownika w przewodniku po architekturze.

Ponowne wywoływanie obliczeń pamiętania po zmianie kluczy

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

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

W tym przypadku użycie funkcji remember powoduje, że wartość MutableState przetrwa rekompozycje.

Ogólnie funkcja remember przyjmuje parametr calculation lambda. Gdy funkcja rememberzostaje uruchomiona po raz pierwszy, wywołuje funkcję lambda calculation i przechowuje jej wynik. Podczas zmiany kompozycji funkcja remember zwraca ostatnio zapisaną wartość.

Oprócz buforowania stanu możesz też używać funkcji remember do przechowywania dowolnego obiektu lub wyniku operacji w kompozycji, której inicjowanie lub obliczanie jest kosztowne. Możesz nie chcieć powtarzać tego obliczenia przy każdym ponownym sformułowaniu. Przykładem jest tworzenie obiektu ShaderBrush, który jest kosztowną operacją:

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

remember zapisuje wartość do momentu jej opuszczenia kompozycji. Istnieje jednak sposób na unieważnienie wartości z pamięci podręcznej. Interfejs API remember przyjmuje też parametr key lub keys. Jeśli któryś z tych kluczy ulegnie zmianie, następnym razem, gdy funkcja zostanie ponownie skompilowana, remember unieważni pamięć podręczną i ponownie wykona obliczenia bloku lambda. Ten mechanizm umożliwia kontrolowanie czasu trwania obiektu w kompozycji. Obliczenie pozostaje ważne do momentu zmiany danych wejściowych, a nie do momentu, gdy zapamiętana wartość opuszcza kompozycję.

Przykłady poniżej pokazują, jak działa ten mechanizm.

W tym fragmencie tworzymy komponent ShaderBrush, który służy jako tło do malowania w komponencie Box. remember przechowuje instancję ShaderBrush, ponieważ jej odtworzenie jest kosztowne, jak wyjaśniono wcześniej. Funkcja remember przyjmuje parametr avatarRes jako key1, czyli wybrany obraz tła. Jeśli wartość avatarRes się zmieni, pędzel ponownie komponuje się z nowym obrazem i ponownie zastosuje format Box. Może się to zdarzyć, gdy użytkownik wybierze inny obraz jako tło z selektora.

@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 kodu stan jest przeniesiony do zwykłej klasy uchwytu stanu MyAppState. Udostępnia funkcję rememberMyAppState do zainicjowania instancji klasy za pomocą remember. Wyświetlanie takich funkcji w celu utworzenia instancji, która przetrwa ponowne skompilowanie, jest typowym wzorcem w Compose. Funkcja rememberMyAppState otrzymuje parametr windowSizeClass, który służy jako parametr key funkcji remember. Jeśli ten parametr ulegnie zmianie, aplikacja musi ponownie utworzyć prostą klasę uchwytu stanu z najnowszą wartością. Może się tak zdarzyć, np. gdy 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 equals klasy, aby określić, czy klucz się zmienił, i unieważnić przechowywaną wartość.

Przechowywanie stanu za pomocą kluczy poza rekompozycją

Interfejs API rememberSaveable to otoczka dla remember, która może przechowywać dane w Bundle. Ten interfejs API umożliwia stanowi przetrwanie nie tylko ponownej kompozycji, lecz także rozrywki czy zainicjowanej przez system śmierci procesu. rememberSaveable otrzymuje parametry input w tym samym celu, w jakim remember otrzymuje parametry keys. Pamięć podręczna jest unieważniana, gdy zmieni się dowolny z danych wejściowych. Gdy funkcja zostanie ponownie skompilowana, rememberSaveable ponownie wykona blok funkcji lambda obliczeń.

W tym przykładzie zmienna rememberSaveable przechowuje wartość zmiennej userTypedQuery, dopóki zmienna typedQuery nie ulegnie zmianie:

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

Więcej informacji

Aby dowiedzieć się więcej o stanie i Jetpack Compose, zapoznaj się z dodatkowymi materiałami poniżej.

Próbki

Ćwiczenia z programowania

Filmy

Blogi