Desliza para actualizar

El componente de deslizar hacia abajo para actualizar permite que los usuarios arrastren hacia abajo al principio del contenido de una app para actualizar los datos.

Superficie de la API

Usa el elemento componible PullToRefreshBox para implementar la función de deslizar hacia abajo para actualizar, que actúa como un contenedor para tu contenido desplazable. Los siguientes parámetros clave controlan el comportamiento y la apariencia de la actualización:

• isRefreshing: Es un valor booleano que indica si la acción de actualización está en curso.
• onRefresh: Es una función lambda que se ejecuta cuando el usuario inicia una actualización.
• indicator: Personaliza el indicador que el sistema dibuja cuando se desliza hacia abajo para actualizar.

Ejemplo básico

En este fragmento, se muestra el uso básico de PullToRefreshBox:

@Composable
fun PullToRefreshBasicSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

Puntos clave sobre el código

• PullToRefreshBox une un LazyColumn, que muestra una lista de cadenas.
• PullToRefreshBox requiere los parámetros isRefreshing y onRefresh.
• El contenido dentro del bloque PullToRefreshBox representa el contenido desplazable.

Resultado

En este video, se muestra la implementación básica de deslizar hacia abajo para actualizar del código anterior:

Ejemplo avanzado: Personaliza el color del indicador

@Composable
fun PullToRefreshCustomStyleSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            Indicator(
                modifier = Modifier.align(Alignment.TopCenter),
                isRefreshing = isRefreshing,
                containerColor = MaterialTheme.colorScheme.primaryContainer,
                color = MaterialTheme.colorScheme.onPrimaryContainer,
                state = state
            )
        },
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

Puntos clave sobre el código

• El color del indicador se personaliza a través de las propiedades containerColor y color en el parámetro indicator.
• rememberPullToRefreshState() administra el estado de la acción de actualización. Usa este estado junto con el parámetro indicator.

Resultado

En este video, se muestra una implementación de deslizar hacia abajo para actualizar con un indicador de color:

Ejemplo avanzado: Crea un indicador completamente personalizado

Puedes crear indicadores personalizados complejos aprovechando los elementos que admiten composición y las animaciones existentes.En este fragmento, se muestra cómo crear un indicador completamente personalizado en tu implementación de deslizar hacia abajo para actualizar:

@Composable
fun PullToRefreshCustomIndicatorSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            MyCustomIndicator(
                state = state,
                isRefreshing = isRefreshing,
                modifier = Modifier.align(Alignment.TopCenter)
            )
        }
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

// ...
@Composable
fun MyCustomIndicator(
    state: PullToRefreshState,
    isRefreshing: Boolean,
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier.pullToRefresh(
            state = state,
            isRefreshing = isRefreshing,
            threshold = PositionalThreshold,
            onRefresh = {

            }
        ),
        contentAlignment = Alignment.Center
    ) {
        Crossfade(
            targetState = isRefreshing,
            animationSpec = tween(durationMillis = CROSSFADE_DURATION_MILLIS),
            modifier = Modifier.align(Alignment.Center)
        ) { refreshing ->
            if (refreshing) {
                CircularProgressIndicator(Modifier.size(SPINNER_SIZE))
            } else {
                val distanceFraction = { state.distanceFraction.coerceIn(0f, 1f) }
                Icon(
                    imageVector = Icons.Filled.CloudDownload,
                    contentDescription = "Refresh",
                    modifier = Modifier
                        .size(18.dp)
                        .graphicsLayer {
                            val progress = distanceFraction()
                            this.alpha = progress
                            this.scaleX = progress
                            this.scaleY = progress
                        }
                )
            }
        }
    }
}
PullToRefreshBox.kt

Puntos clave sobre el código

• En el fragmento anterior, se usó el Indicator que proporciona la biblioteca. Este fragmento crea un indicador componible personalizado llamado MyCustomIndicator. En este elemento componible, el modificador pullToRefreshIndicator controla el posicionamiento y activa una actualización.
• Al igual que en el fragmento anterior, en el ejemplo, se extrae la instancia de PullToRefreshState para que puedas pasar la misma instancia a PullToRefreshBox y a pullToRefreshModifier.
• En el ejemplo, se usan el color del contenedor y el umbral de posición de la clase PullToRefreshDefaults. De esta manera, puedes reutilizar el comportamiento y el estilo predeterminados de la biblioteca de Material y, al mismo tiempo, personalizar solo los elementos que te interesan.
• MyCustomIndicator usa Crossfade para realizar la transición entre un ícono de nube y un CircularProgressIndicator. El ícono de nube se amplía a medida que el usuario desliza el dedo hacia abajo y cambia a un CircularProgressIndicator cuando comienza la acción de actualización.
  • targetState usa isRefreshing para determinar qué estado mostrar (el ícono de nube o el indicador de progreso circular).
  • animationSpec define una animación tween para la transición, con una duración especificada de CROSSFADE_DURATION_MILLIS.
  • state.distanceFraction representa cuánto deslizó el usuario hacia abajo, desde 0f (sin deslizamiento) hasta 1f (deslizamiento completo).
  • El modificador graphicsLayer modifica la escala y la transparencia.

Resultado

En este video, se muestra el indicador personalizado del código anterior:

Recursos adicionales

• PullToRefreshState