Efectos secundarios en Compose

Los elementos componibles no deberían tener efectos secundarios. Sin embargo, cuando sea necesario para mutar el estado de la app, se los debe llamar desde un entorno controlado que reconozca el ciclo de vida del elemento componible. En esta página, aprenderás sobre las diferentes API de efectos secundarios que brinda Jetpack Compose.

Casos de uso de los efectos y estados

Como se explica en la documentación Cómo pensar en Compose, los elementos componibles deben tener efectos secundarios. Cuando necesites realizar cambios en el estado de la app (como se describe en el documento Cómo administrar la documentación de estados), deberás usar las API de Effects para que esos efectos secundarios se ejecuten de manera predecible.

Debido a las diferentes posibilidades que ofrecen los efectos en Compose, pueden ser fácilmente sobrecargados. Asegúrate de que el trabajo que realices en ellos esté relacionado con la IU y no divida el flujo de datos unidireccional, como se explica en la documentación de administración de estados.

LaunchedEffect: Ejecuta funciones de suspensión en el alcance de un elemento componible

Para llamar a funciones de suspensión de forma segura dentro de un elemento componible, usa el objeto LaunchedEffect compatible. Cuando LaunchedEffect ingresa a Composition, inicia una corrutina con el bloque de código pasado como un parámetro. La corrutina se cancelará si LaunchedEffect sale de la composición. Si se recompone LaunchedEffect con diferentes claves (consulta a continuación la sección Cómo reiniciar efectos), la corrutina existente se cancelará y se iniciará la nueva función de suspensión en una corrutina nueva.

Por ejemplo, mostrar una Snackbar en una Scaffold se realiza con la función SnackbarHostState.showSnackbar, que es una suspensión.

@Composable
fun MyScreen(
    state: UiState<List<Movie>>,
    scaffoldState: ScaffoldState = rememberScaffoldState()
) {

    // If the UI state contains an error, show snackbar
    if (state.hasError) {

        // `LaunchedEffect` will cancel and re-launch if
        // `scaffoldState.snackbarHostState` changes
        LaunchedEffect(scaffoldState.snackbarHostState) {
            // Show snackbar using a coroutine, when the coroutine is cancelled the
            // snackbar will automatically dismiss. This coroutine will cancel whenever
            // `state.hasError` is false, and only start when `state.hasError` is true
            // (due to the above if-check), or if `scaffoldState.snackbarHostState` changes.
            scaffoldState.snackbarHostState.showSnackbar(
                message = "Error message",
                actionLabel = "Retry message"
            )
        }
    }

    Scaffold(scaffoldState = scaffoldState) {
        /* ... */
    }
}

En el código anterior, una corrutina se activa si el estado contiene un error y se cancela cuando no lo tiene. Como el sitio de llamadas de LaunchedEffect está dentro de una declaración "if", cuando la declaración es "false", si LaunchedEffect estaba en Composition, se la quitará y, por lo tanto, se cancelará la corrutina.

RememberCoroutineScope: Obtén un alcance compatible con la composición para iniciar una corrutina fuera de un elemento componible

Dado que LaunchedEffect es una función que admite composición, solo se puede usar dentro de otras funciones de ese tipo. Para iniciar una corrutina fuera de un elemento componible, pero con un alcance definido que se cancelará automáticamente una vez que salga de la composición, usa rememberCoroutineScope. Además, puedes usar rememberCoroutineScope cada vez que necesites controlar el ciclo de vida de una o más corrutinas de forma manual; por ejemplo, para cancelar una animación cuando se produce un evento de usuario.

rememberCoroutineScope es una función que admite composición que muestra un CoroutineScope vinculado al punto de Composition al que se llama. El alcance se cancelará cuando la llamada salga de Composition.

Siguiendo el ejemplo anterior, puedes usar este código para mostrar una Snackbar cuando el usuario presiona un Button:

@Composable
fun MoviesScreen(scaffoldState: ScaffoldState = rememberScaffoldState()) {

    // Creates a CoroutineScope bound to the MoviesScreen's lifecycle
    val scope = rememberCoroutineScope()

    Scaffold(scaffoldState = scaffoldState) {
        Column {
            /* ... */
            Button(
                onClick = {
                    // Create a new coroutine in the event handler
                    // to show a snackbar
                    scope.launch {
                        scaffoldState.snackbarHostState
                            .showSnackbar("Something happened!")
                    }
                }
            ) {
                Text("Press me")
            }
        }
    }
}

RemindUpdatedState: Haz referencia a un valor en un efecto que no se debe reiniciar si cambia el valor

LaunchedEffect se reinicia cuando cambia uno de los parámetros clave. Sin embargo, en algunas situaciones, puede que quieras capturar un valor en tu efecto que, si cambia, no quieres que se reinicie. Para ello, debes usar rememberUpdatedState a fin de crear una referencia a ese valor que se puede capturar y actualizar. Este enfoque es útil para efectos que contienen operaciones de larga duración que pueden ser costosas o imposibles de recrear y reiniciar.

Por ejemplo, supongamos que tu app tiene una LandingScreen que desaparece después de un tiempo. Incluso si se vuelve a componer LandingScreen, el efecto que espera unos segundos y notifica que ya transcurrió el tiempo no debería reiniciarse:

@Composable
fun LandingScreen(onTimeout: () -> Unit) {

    // This will always refer to the latest onTimeout function that
    // LandingScreen was recomposed with
    val currentOnTimeout by rememberUpdatedState(onTimeout)

    // Create an effect that matches the lifecycle of LandingScreen.
    // If LandingScreen recomposes, the delay shouldn't start again.
    LaunchedEffect(true) {
        delay(SplashWaitTimeMillis)
        currentOnTimeout()
    }

    /* Landing screen content */
}

Para crear un efecto que coincida con el ciclo de vida del sitio de llamada, se pasa como parámetro una constante inmutable, como Unit o true. En el código anterior, se usa LaunchedEffect(true). Para asegurarte de que la lambda onTimeout siempre contenga el valor más reciente con el que se volvió a componer LandingScreen, onTimeout debe unirse a la función rememberUpdatedState. El objeto State que se muestra, currentOnTimeout en el código, se debe usar en el efecto.

DisposableEffect: Efectos que requieren limpieza

Para los efectos secundarios que se deben limpiar después de que cambian las claves o si el elemento componible deja Composition, usa DisposableEffect. Si cambian las claves DisposableEffect, el elemento que admite composición debe descartar (eliminar) su efecto actual y restablecerlo llamando otra vez al efecto.

Por ejemplo, un elemento OnBackPressedCallback debe estar registrado para escuchar cuando se presione el botón Atrás en un OnBackPressedDispatcher. Para escuchar esos eventos en Compose, utiliza un DisposableEffect a fin de registrar y dejar de registrar la devolución de llamada cuando sea necesario.

@Composable
fun BackHandler(backDispatcher: OnBackPressedDispatcher, onBack: () -> Unit) {

    // Safely update the current `onBack` lambda when a new one is provided
    val currentOnBack by rememberUpdatedState(onBack)

    // Remember in Composition a back callback that calls the `onBack` lambda
    val backCallback = remember {
        // Always intercept back events. See the SideEffect for
        // a more complete version
        object : OnBackPressedCallback(true) {
            override fun handleOnBackPressed() {
                currentOnBack()
            }
        }
    }

    // If `backDispatcher` changes, dispose and reset the effect
    DisposableEffect(backDispatcher) {
        // Add callback to the backDispatcher
        backDispatcher.addCallback(backCallback)

        // When the effect leaves the Composition, remove the callback
        onDispose {
            backCallback.remove()
        }
    }
}

En el código anterior, el efecto agregará la backCallback recordada a backDispatcher. Si cambia backDispatcher, el efecto se descarta y se reinicia nuevamente.

Un DisposableEffect debe incluir una cláusula onDispose como declaración final en su bloque de código. De lo contrario, el IDE mostrará un error de tiempo de compilación.

SideEffect: Publica el estado de Compose en código no componible

Para compartir el estado de Compose con objetos que no administra la composición, usa el elemento componible SideEffect, ya que se invoca en cada recomposición exitosa.

Tomando el código BackHandler anterior como ejemplo, a fin de comunicar si se debe habilitar o no la devolución de llamada, usa SideEffect para actualizar su valor.

@Composable
fun BackHandler(
    backDispatcher: OnBackPressedDispatcher,
    enabled: Boolean = true, // Whether back events should be intercepted or not
    onBack: () -> Unit
) {
    /* ... */
    val backCallback = remember { /* ... */ }

    // On every successful composition, update the callback with the `enabled` value
    // to tell `backCallback` whether back events should be intercepted or not
    SideEffect {
        backCallback.isEnabled = enabled
    }

    /* Rest of the code */
}

produceState: Convierte un estado que no sea de Compose en uno que sí lo sea

produceState lanza una corrutina orientada al objeto Composition que puede enviar valores a un State que se muestra. Úsalo para convertir el estado que no sea de Compose en uno que sí lo sea, por ejemplo, llevando el estado externo controlado por suscripciones, como Flow, LiveData o RxJava, a Composition.

El productor se lanza cuando produceState ingresa a Composition y se cancela cuando sale de allí. El State que se muestra se combina; si estableces el mismo valor, no se activará una recomposición.

Por más que produceState cree una corrutina, también se puede usar para observar fuentes de datos que no están suspendidas. Para quitar la suscripción a esa fuente, usa la función awaitDispose.

En el siguiente ejemplo, se muestra cómo usar produceState para cargar una imagen desde la red. La función que admite composición loadNetworkImage muestra un State que se puede usar en otros elementos componibles.

@Composable
fun loadNetworkImage(
    url: String,
    imageRepository: ImageRepository
): State<Result<Image>> {

    // Creates a State<T> with Result.Loading as initial value
    // If either `url` or `imageRepository` changes, the running producer
    // will cancel and will be re-launched with the new keys.
    return produceState(initialValue = Result.Loading, url, imageRepository) {

        // In a coroutine, can make suspend calls
        val image = imageRepository.load(url)

        // Update State with either an Error or Success result.
        // This will trigger a recomposition where this State is read
        value = if (image == null) {
            Result.Error
        } else {
            Result.Success(image)
        }
    }
}
.

derivedStateOf: Convierte uno o varios objetos de estado en otro estado

Usa derivedStateOf cuando se calcula o deriva un estado determinado de otros objetos de estado. El uso de esta función garantiza que el cálculo solo ocurrirá cuando cambie uno de los estados del cálculo.

En el siguiente ejemplo, se muestra una lista básica de pendientes cuyas tareas con palabras clave de prioridad alta definidas por usuarios aparecen primero:

@Composable
fun TodoList(
    highPriorityKeywords: List<String> = listOf("Review", "Unblock", "Compose")
) {
    val todoTasks = remember { mutableStateListOf<String>() }

    // Calculate high priority tasks only when the todoTasks or
    // highPriorityKeywords change, not on every recomposition
    val highPriorityTasks by remember(todoTasks, highPriorityKeywords) {
        derivedStateOf {
            todoTasks.filter { it.containsWord(highPriorityKeywords) }
        }
    }

    Box(Modifier.fillMaxSize()) {
        LazyColumn {
            items(highPriorityTasks) { /* ... */ }
            items(todoTasks) { /* ... */ }
        }
        /* Rest of the UI where users can add elements to the list */
    }
}

En el código anterior, derivedStateOf garantiza que cuando cambien todoTasks o highPriorityKeywords, se realizará el cálculo highPriorityTasks y se actualizará la IU según corresponda. Dado que el filtrado para calcular highPriorityTasks puede ser costoso, solo se debe ejecutar cuando cambia alguna de las listas, no en todas las recomposiciones.

Además, una actualización del estado producida por derivedStateOf no hace que se vuelva a componer el elemento componible en el que se declara. Compose solo vuelve a componer esos elementos componibles donde el estado que se muestra es leído (en el ejemplo, dentro de LazyColumn).

snapshotFlow: Convierte el estado de Compose en flujos

Usa snapshotFlow para convertir objetos State<T> en un flujo frío. snapshotFlow ejecuta su bloque cuando se recopila y emite el resultado de los objetos State que se leen en él. Cuando cambia uno de los objetos State leídos dentro del bloque snapshotFlow, el flujo emitirá el nuevo valor a su colector si este no es igual al valor emitido con anterioridad (este comportamiento es similar al de Flow.distinctUntilChanged).

En el siguiente ejemplo, se muestra un efecto secundario que registra cuándo el usuario se desplaza más allá del primer elemento de una lista de estadísticas:

val listState = rememberLazyListState()

LazyColumn(state = listState) {
    // ...
}

LaunchedEffect(listState) {
    snapshotFlow { listState.firstVisibleItemIndex }
        .map { index -> index > 0 }
        .distinctUntilChanged()
        .filter { it == true }
        .collect {
            MyAnalyticsService.sendScrolledPastFirstItemEvent()
        }
}

En el código anterior, listState.firstVisibleItemIndex se convierte en un flujo que puede beneficiarse de la potencia de los operadores de flujo.

Cómo reiniciar efectos

Algunos efectos de Compose, como LaunchedEffect, produceState o DisposableEffect, toman una cantidad variable de argumentos, claves, que se usan para cancelar el efecto de ejecución y comenzar uno nuevo con las nuevas claves.

El formato típico de estas API es el siguiente:

EffectName(restartIfThisKeyChanges, orThisKey, orThisKey, ...) { block }

Debido a las sutilezas de este comportamiento, pueden generarse problemas si los parámetros usados para reiniciar el efecto no son los adecuados:

  • Reiniciar los efectos con menor frecuencia de la debida podría generar errores en tu app.
  • Reiniciarlos en exceso podría hacer que su uso sea ineficiente.

Como regla general, las variables inmutables y mutables que se usan en el bloque de código de efecto deben agregarse como parámetros para el efecto componible. Además de esos, se pueden agregar más parámetros para forzar el reinicio del efecto. Si el cambio de una variable no debería causar el efecto del reinicio, la variable debe unirse en rememberUpdatedState. Si la variable no cambia porque se une a un remember sin claves, no necesitas pasar la variable como una clave para el efecto.

En el código DisposableEffect que se muestra arriba, el efecto toma como parámetro el backDispatcher que se usa en su bloque, ya que cualquier cambio él provocaría que se reinicie el efecto.

@Composable
fun BackHandler(backDispatcher: OnBackPressedDispatcher, onBack: () -> Unit) {
    /* ... */
    val backCallback = remember { /* ... */ }

    DisposableEffect(backDispatcher) {
        backDispatcher.addCallback(backCallback)
        onDispose {
            backCallback.remove()
        }
    }
}

backCallback no es necesaria como una clave DisposableEffect porque su valor nunca cambiará en Composition. Queda unido a un remember sin claves. Si no se pasa backDispatcher como parámetro y cambia, se volverá a componer BackHandler, pero no se descartará DisposableEffect ni se reiniciará. Eso generará problemas, ya que se usará un backDispatcher incorrecto a partir de ese momento.

Constantes como claves

Puedes usar una constante como true como clave de efecto para que siga el ciclo de vida del sitio de llamadas. Hay casos de uso válidos para eso, como el ejemplo de LaunchedEffect que se muestra arriba. Sin embargo, antes de hacer eso, piensa dos veces y asegúrate de que sea lo que necesitas.