State e Jetpack Compose

Lo stato in un'app è qualsiasi valore che può cambiare nel tempo. Si tratta di una definizione molto ampia che comprende tutto, da un database Room a una variabile in una classe.

Tutte le app Android mostrano lo stato all'utente. Ecco alcuni esempi di stato nelle app Android:

• Una barra di notifica che viene visualizzata quando non è possibile stabilire una connessione di rete.
• Un post del blog e i commenti associati.
• Animazioni di ondulazione sui pulsanti che vengono riprodotte quando un utente li fa clic.
• Adesivi che un utente può disegnare sopra un'immagine.

Jetpack Compose ti aiuta a specificare dove e come memorizzi e utilizzi lo stato in un'app per Android. Questa guida si concentra sul collegamento tra stato e composabili e sulle API offerte da Jetpack Compose per lavorare con lo stato più facilemente.

Stato e composizione

Compose è dichiarativo e, pertanto, l'unico modo per aggiornarlo è chiamare lo stesso composable con nuovi argomenti. Questi argomenti sono rappresentazioni dello stato dell'interfaccia utente. Ogni volta che viene aggiornato uno stato, viene eseguita una ricostituzione. Di conseguenza, elementi come TextField non si aggiornano automaticamente come nelle visualizzazioni imperative basate su XML. A un composable deve essere comunicato esplicitamente il nuovo stato per consentirgli di aggiornarsi di conseguenza.

@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

Se esegui questo comando e provi a inserire del testo, vedrai che non succede niente. Questo accade perché TextField non si aggiorna autonomamente, ma quando cambia il parametro value. Ciò è dovuto al funzionamento della composizione e della ricostituzione in Compose.

Termine chiave: Composizione:una descrizione della UI creata da Jetpack Compose per l'esecuzione degli elementi componibili.

Composizione iniziale:creazione di una composizione mediante l'esecuzione dei composabili per la prima volta.

Ricomposizione: esecuzione di nuovo dei composabili per aggiornare la composizione quando i dati cambiano.

Per scoprire di più sulla composizione iniziale e sulla ricompozione, consulta Pensare in Compose.

Stato nei componibili

Le funzioni componibili possono utilizzare l'API remember per memorizzare un oggetto in memoria. Un valore calcolato da remember viene archiviato nella composizione durante la composizione iniziale e il valore archiviato viene restituito durante la ricomposizione. È possibile utilizzare remember per archiviare oggetti sia mutabili che immutabili.

Nota: remember archivia gli oggetti nella composizione e dimentica l'oggetto quando il componibile chiamato remember viene rimosso dalla composizione.

mutableStateOf crea un osservato MutableState<T>, che è un tipo di osservato integrato con il runtime di compose.

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

Eventuali modifiche a value pianificano la ricompozione di eventuali funzioni composable che leggono value.

Esistono tre modi per dichiarare un oggetto MutableState in un composable:

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

Queste dichiarazioni sono equivalenti e vengono fornite come sintassi alternativa per diversi utilizzi dello stato. Scegli quello che produce il codice più facile da leggere nel componibile che stai scrivendo.

La sintassi del delegato by richiede le seguenti importazioni:

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

Puoi utilizzare il valore memorizzato come parametro per altri composabili o persino come logica nelle istruzioni per modificare i composabili visualizzati. Ad esempio, se non vuoi mostrare il saluto se il nome è vuoto, utilizza lo stato in un statement 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

Sebbene remember ti aiuti a mantenere lo stato durante le ricostruzioni, lo stato non viene conservato durante le modifiche alla configurazione. Per farlo, devi utilizzare rememberSaveable. rememberSaveable salva automaticamente qualsiasi valore che può essere memorizzato in un Bundle. Per altri valori, puoi trasferire un oggetto salvaschermo personalizzato.

Attenzione: l'utilizzo di oggetti mutabili come ArrayList<T> o mutableListOf() come stato in Compose fa sì che gli utenti vedano dati errati o obsoleti nella tua app. Gli oggetti mutabili non osservabili, come ArrayList o una classe di dati mutabili, non sono osservabili da Compose e non attivano una ricompozione quando cambiano. Invece di utilizzare oggetti mutevoli non osservabili, ti consigliamo di utilizzare un titolare di dati osservabili come State<List<T>> e l'immutabile listOf().

Altri tipi di stato supportati

Compose non richiede l'utilizzo di MutableState<T> per conservare lo stato; supporta altri tipi osservabili. Prima di leggere un altro tipo di elemento osservabile in Compose, devi convertirlo in State<T> in modo che i componenti composibili possano ricomporsi automaticamente quando cambia lo stato.

Compose viene fornito con funzioni per creare State<T> da tipi osservabili comuni utilizzati nelle app per Android. Prima di utilizzare queste integrazioni, aggiungi gli elementi appropriati come descritto di seguito:

• Flow: collectAsStateWithLifecycle()

  collectAsStateWithLifecycle() raccoglie i valori da un Flow tenendo conto del ciclo di vita, consentendo alla tua app di risparmiare risorse dell'app. Rappresenta l'ultimo valore emesso da Compose State. Utilizza questa API come metodo consigliato per raccogliere i flussi sulle app Android.

  Nota: per scoprire di più su come raccogliere i flussi in sicurezza in Android con l'APIcollectAsStateWithLifecycle() , puoi leggere questo post del blog.

  Nel file build.gradle è richiesta la seguente dipendenza (deve essere 2.6.0-beta01 o successiva):

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 è simile a collectAsStateWithLifecycle, perché raccoglie anche i valori da un Flow e li trasforma in Compose State.

  Utilizza collectAsState per il codice indipendente dalla piattaforma anziché collectAsStateWithLifecycle, che è solo per Android.

  Non sono necessarie dipendenze aggiuntive per collectAsState, perché è disponibile in compose-runtime.

• LiveData: observeAsState()

  observeAsState() inizia a osservare questo LiveData e ne rappresenta i valori tramite State.

  Nel file build.gradle è obbligatoria la seguente dipendenza:

Kotlin

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

Groovy

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

• RxJava2: subscribeAsState()

  subscribeAsState() sono funzioni di estensione che trasformano i flussi reattivi di RxJava2 (ad es. Single, Observable, Completable) in Compose State.

  Nel file build.gradle è obbligatoria la seguente dipendenza:

Kotlin

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

Groovy

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

• RxJava3: subscribeAsState()

  subscribeAsState() sono funzioni di estensione che trasformano gli stream reattivi di RxJava3 (ad es. Single, Observable, Completable) in Compose State.

  Nel file build.gradle è obbligatoria la seguente dipendenza:

Kotlin

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

Groovy

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

Punto chiave: Compose esegue automaticamente la ricompozione dalla lettura degli oggetti State. Se utilizzi un altro tipo di osservabile come LiveData in Compose, devi convertirlo in State prima di leggerlo. Assicurati che la conversione del tipo avvenga in un componibile, utilizzando una funzione di estensione componibile come LiveData<T>.observeAsState().

Nota: queste integrazioni non sono limitate. Puoi creare una funzione di estensione per Jetpack Compose che legga altri tipi di oggetti osservabili. Se la tua app utilizza una classe osservabile personalizzata, convertila per generare State<T> utilizzando l'API produceState.

Guarda l'implementazione degli elementi integrati per esempi di come farlo: collectAsStateWithLifecycle. Qualsiasi oggetto che consenta a Jetpack Compose di sottoscrivere ogni modifica può essere convertito in State<T> e letto in un elemento Composable.

Stateful e stateless

Un composable che utilizza remember per archiviare un oggetto crea uno stato interno, rendendo il composable con stato. HelloContent è un esempio di composable con stato perché gestisce e modifica internamente il proprio stato name. Questo può essere utile in situazioni in cui chi chiama non ha bisogno di controllare lo stato e può utilizzarlo senza dover gestire lo stato stesso. Tuttavia, i composabili con stato interno tendono a essere meno riutilizzabili e più difficili da testare.

Un composable senza stato è un composable che non memorizza alcun stato. Un modo semplice per ottenere uno stato stateless è utilizzare l'elevatore di stato.

Quando sviluppi elementi componibili riutilizzabili, spesso desideri esporre sia una versione stateful che una versione stateless dello stesso componibile. La versione stateful è comoda per i chiamanti che non sono interessati allo stato, mentre la versione stateless è necessaria per i chiamanti che devono controllare o aumentare lo stato.

Innalzamento dello stato

L'elevazione dello stato in Compose è un pattern che sposta lo stato all'autore di un composable per creare un composable senza stato. Il pattern generale per l'elevazione dello stato in Jetpack Compose è sostituire la variabile di stato con due parametri:

• value: T: il valore corrente da visualizzare
• onValueChange: (T) -> Unit: un evento che richiede la modifica del valore, dove T è il nuovo valore proposto

Tuttavia, non sei limitato a onValueChange. Se per il composable sono appropriati eventi più specifici, devi definirli utilizzando le lambda.

Lo stato sollevato in questo modo ha alcune proprietà importanti:

• Unica fonte attendibile: spostando lo stato anziché duplicarlo, garantiamo che esista un'unica fonte attendibile. In questo modo puoi evitare bug.
• Incapsulati:solo i composabili con stato possono modificarlo. È completamente interno.
• Condiviso:lo stato in primo piano può essere condiviso con più composabili. Se vuoi leggere name in un componibile diverso, sollevamento consente di farlo.
• Intercettabili:gli utenti che chiamano i composabili stateless possono decidere di ignorare o modificare gli eventi prima di modificare lo stato.
• Disaccoppiato: lo stato dei componenti componibili stateless può essere archiviato ovunque. Ad esempio, ora è possibile spostare name in un ViewModel.

Nell'esempio, estrai name e onValueChange da HelloContent e li sposti verso l'alto dell'albero in un composable HelloScreen che chiama 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

Se estrai lo stato da HelloContent, è più facile ragionare sul composable, riutilizzarlo in situazioni diverse e testarlo. HelloContent è indipendente dal modo in cui viene archiviato il relativo stato. Il disaccoppiamento significa che se modifichi o sostituisci HelloScreen, non devi cambiare la modalità di implementazione di HelloContent.

Il pattern in cui lo stato diminuisce e gli eventi aumentano è chiamato flusso di dati unidirezionale. In questo caso, lo stato passa da HelloScreen a HelloContent e gli eventi aumentano da HelloContent a HelloScreen. Seguendo il flusso di dati unidirezionale, puoi disaccoppiare i composabili che mostrano lo stato nell'interfaccia utente dalle parti dell'app che memorizzano e modificano lo stato.

Punto chiave:quando sollevi lo stato, ci sono tre regole che ti aiutano a capire dove deve essere inserito:

1. Lo stato deve essere sollevato almeno al livello del composito di primo livello di tutti i composabili che utilizzano lo stato (in lettura).
2. Lo stato deve essere sollevato almeno al livello più alto in cui può essere modificato (scrittura).
3. Se due stati cambiano in risposta agli stessi eventi, devono essere caricati insieme.

Puoi eseguire l'hoisting dello stato più in alto di quanto richiesto da queste regole, ma l'hoisting dello stato ridotto rende difficile o impossibile seguire il flusso di dati unidirezionale.

Per scoprire di più, consulta la pagina Dove eseguire l'hoisting dello stato.

Ripristino dello stato in Compose

L'API rememberSaveable si comporta in modo simile a remember perché conserva lo stato durante le ricostruzioni e anche durante la ricreazione di attività o processi utilizzando il meccanismo dello stato dell'istanza salvato. Ad esempio, questo accade quando lo schermo viene ruotato.

Nota: rememberSaveable non manterrà lo stato se l'attività viene chiusa completamente dall'utente. Ad esempio, non mantiene lo stato se l'utente sblocca l'attività corrente dalla schermata Recenti.

Modalità di memorizzazione dello stato

Tutti i tipi di dati aggiunti a Bundle vengono salvati automaticamente. Se vuoi salvare qualcosa che non può essere aggiunto a Bundle, hai a disposizione diverse opzioni.

Parcellare

La soluzione più semplice consiste nell'aggiungere l'annotazione @Parcelize all'oggetto. L'oggetto diventa frazionabile e può essere raggruppato. Ad esempio, questo codice crea un tipo di dati City partizionabili e lo salva nello stato.

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

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

Salvatore Map

Se per qualche motivo @Parcelize non è adatto, puoi utilizzare mapSaver per definire la tua regola per convertire un oggetto in un insieme di valori che il sistema può salvare in 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

Per evitare di dover definire le chiavi per la mappa, puoi anche utilizzare listSaver e utilizzare i relativi indici come chiavi:

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

Contenitori di stato in Compose

Il semplice sollevamento dello stato può essere gestito nelle funzioni componibili stesse. Tuttavia, se la quantità di stato da monitorare aumenta o se si presenta la logica da eseguire nelle funzioni componibili, è buona prassi delegare le responsabilità relative alla logica e allo stato ad altri oggetti: i contenitori di stato.

Termine chiave: i contenitori dello stato gestiscono la logica e lo stato dei composabili.

Tieni presente che in altri materiali, i detentori di stato sono chiamati anche oggetti di stato elevati.

Per scoprire di più, consulta la documentazione sull'elevatore dello stato in Compose o, più in generale, la pagina Contenitori dello stato e stato dell'interfaccia utente nella guida all'architettura.

Riattiva i calcoli di memorizzazione quando le chiavi cambiano

L'API remember viene utilizzata spesso insieme a MutableState:

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

In questo caso, l'utilizzo della funzione remember consente al valore MutableState di sopravvivere alle ricostruzioni.

In generale, remember richiede un parametro lambda calculation. Quando remember viene eseguito per la prima volta, richiama la funzione lambda calculation e ne memorizza il risultato. Durante la recomposizione, remember restituisce l'ultimo valore memorizzato.

Oltre a memorizzare nella cache lo stato, puoi utilizzare remember anche per archiviare qualsiasi oggetto o risultato di un'operazione nella composizione che è costoso da inizializzare o calcolare. Potresti non voler ripetere questo calcolo in ogni ricompozione. Un esempio è la creazione di questo oggetto ShaderBrush, un'operazione costosa:

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

remember memorizza il valore finché non esce dalla composizione. Tuttavia, esiste un modo per invalidare il valore memorizzato nella cache. L'API remember accetta anche un parametro key o keys. Se una di queste chiavi cambia, alla successiva ricomposizione della funzione, remember non convalida la cache ed esegue nuovamente il calcolo del blocco lambda. Questo meccanismo ti consente di controllare il ciclo di vita di un oggetto nella composizione. Il calcolo rimane valido fino a quando gli input non cambiano, anziché fino a quando il valore memorizzato non esce dalla composizione.

I seguenti esempi mostrano come funziona questo meccanismo.

In questo snippet viene creato un elemento ShaderBrush, che viene utilizzato come sfondo di un componibile Box. remember memorizza l'istanza ShaderBrush perché è costoso ricrearla, come spiegato in precedenza. remember accettaavatarRes come parametro key1, ovvero l'immagine di sfondo selezionata. Se avatarRes cambia, il pennello si ricomporrà con la nuova immagine e verrà riapplicato a Box. Questo può accadere quando l'utente seleziona un'altra immagine da usare come sfondo da un selettore.

@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

Nello snippet successivo, lo stato viene trasferito a una classe di stato normale MyAppState. Espone una funzione rememberMyAppState per inizializzare un'istanza della classe utilizzando remember. L'esposizione di queste funzioni per creare un'istanza che sopravviva alle ricostruzioni è uno schema comune in Compose. La funzione rememberMyAppState riceve windowSizeClass, che funge da parametro key per remember. Se questo parametro cambia, l'app deve rielaborare la classe del detentore dello stato normale con il valore più recente. Questo può accadere, ad esempio, se l'utente ruota il dispositivo.

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

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

Nota: per ulteriori informazioni sulle classi di detentori di stato semplici, consulta la documentazione relativa alla classe di detentore di stato semplice come proprietario dello stato o la documentazione relativa a Detentori di stato e stato dell'interfaccia utente nella guida all'architettura.

Compose utilizza l'implementazione di equals della classe per decidere se una chiave è stata modificata e per invalidare il valore memorizzato.

Nota: a prima vista, l'utilizzo di remember con le chiavi potrebbe sembrare simile all'utilizzo di altre API Compose, come derivedStateOf. Per scoprire la differenza, consulta il post del blog Jetpack Compose: quando devo usare derivedStateOf?.

Memorizzare lo stato con chiavi oltre la ricostituzione

L'API rememberSaveable è un wrapper di remember che può memorizzare i dati in un Bundle. Questa API consente allo stato di sopravvivere non solo alla ricompozione, ma anche alla ricreazione delle attività e all'interruzione del processo avviata dal sistema. rememberSaveable riceve i parametri input per lo stesso scopo per cui remember riceve keys. La cache viene invalidata quando uno degli input cambia. La volta successiva che la funzione si ricomporrà, rememberSaveable eseguirà nuovamente il blocco lambda di calcolo.

Nota: c'è una differenza nella denominazione delle API che dovresti notare. Nell'API remember utilizzi il nome parametro keys e in rememberSaveable utilizzi inputs per lo stesso scopo. Se uno di questi parametri cambia, il valore memorizzato nella cache viene invalidato.

Nell'esempio seguente, rememberSaveable memorizza userTypedQuery finché typedQuery non cambia:

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

Scopri di più

Per scoprire di più sullo stato e su Jetpack Compose, consulta le seguenti risorse aggiuntive.

Campioni

Codelab

• Utilizzare State in Jetpack Compose

Video

• Uno stato d'animo per la composizione

Blog

• Gestione efficace dello stato per TextField in Compose