Desliza para actualizar

El componente de actualización por arrastre permite a los usuarios arrastrar hacia abajo al comienzo del contenido de una app para actualizar los datos.

Superficie de la API

Usa el elemento componible PullToRefreshBox para implementar la función de actualización por arrastre, 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 en la función de actualización por arrastre.

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) })
            }
        }
    }
}

Puntos clave sobre el código

  • PullToRefreshBox incluye 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 la función de actualización por arrastre del código anterior:

Figura 1 : Implementación básica de la función de actualización por arrastre en una lista de elementos

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) })
            }
        }
    }
}

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. Usas este estado junto con el parámetro indicator.

Resultado

En este video, se muestra una implementación de la función de actualización por arrastre con un indicador de color:

Figura 2 : Implementación de la función de actualización por arrastre con un estilo personalizado

Ejemplo avanzado: Crea un indicador completamente personalizado

Puedes crear indicadores personalizados complejos aprovechando los elementos componibles y las animaciones existentes.En este fragmento, se muestra cómo crear un indicador completamente personalizado en tu implementación de la función de actualización por arrastre:

@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
                        }
                )
            }
        }
    }
}

Puntos clave sobre el código

  • En el fragmento anterior, se usó el Indicator que proporciona la biblioteca. En este fragmento, se crea un elemento componible de indicador 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, el ejemplo extrae la instancia PullToRefreshState, por lo que puedes 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, mientras personalizas 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 tira y pasa 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 la distancia que el usuario arrastró hacia abajo, desde 0f (sin arrastre) hasta 1f (arrastre completo).
    • El modificador graphicsLayer modifica la escala y la transparencia.

Resultado

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

Figura 3 : Implementación de la función de actualización por arrastre con un indicador personalizado

Recursos adicionales