Indicadores de progreso

Los indicadores de progreso muestran visualmente el estado de una operación. Usan el movimiento para llamar la atención del usuario sobre el grado de avance del proceso, como la carga o el procesamiento de datos. También pueden indicar que se está realizando el procesamiento, sin hacer referencia a qué tan cerca de la finalización podría estar.

Considera estos tres casos de uso en los que podrías usar un indicador de progreso:

  • Carga de contenido: Cuando se recupera contenido de una red, como la carga de una imagen o datos para un perfil de usuario
  • Carga de archivos: Brinda comentarios al usuario sobre cuánto tiempo podría tardar la carga.
  • Procesamiento prolongado: Mientras una app procesa una gran cantidad de datos, indícale al usuario qué porcentaje del total se completó.

En Material Design, existen dos tipos de indicadores de progreso:

  • Determinada: Muestra exactamente cuánto progreso se logró.
  • Indeterminate: Se anima de forma continua sin tener en cuenta el progreso.

Del mismo modo, un indicador de progreso puede adoptar una de las siguientes dos formas:

  • Lineal: Una barra horizontal que se llena de izquierda a derecha.
  • Circular: Un círculo cuyo trazo crece en longitud hasta abarcar toda la circunferencia del círculo.
Un indicador de progreso lineal junto a un indicador de progreso circular.
Figura 1: Los dos tipos de indicadores de progreso.

Superficie de la API

Si bien hay varios elementos componibles que puedes usar para crear indicadores de progreso coherentes con Material Design, sus parámetros no difieren demasiado. Entre los parámetros clave que debes tener en cuenta, se incluyen los siguientes:

  • progress: Es el progreso actual que muestra el indicador. Pasa un Float entre 0.0 y 1.0.
  • color: Es el color del indicador real. Es decir, la parte del componente que refleja el progreso y que abarca por completo el componente cuando se completa el progreso.
  • trackColor: Es el color del segmento sobre el que se dibuja el indicador.

Indicadores determinantes

Un indicador determinado refleja exactamente qué tan completa es una acción. Usa los elementos LinearProgressIndicator o CircularProgressIndicator componibles y pasa un valor para el parámetro progress.

En el siguiente fragmento, se proporciona un ejemplo relativamente detallado. Cuando el usuario presiona el botón, la app muestra el indicador de progreso y, además, inicia una corrutina que aumenta gradualmente el valor de progress. Esto hace que el indicador de progreso aumente de forma iterativa.

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableStateOf(0f) }
    var loading by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope() // Create a coroutine scope

    Column(
        verticalArrangement = Arrangement.spacedBy(12.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        modifier = Modifier.fillMaxWidth()
    ) {
        Button(onClick = {
            loading = true
            scope.launch {
                loadProgress { progress ->
                    currentProgress = progress
                }
                loading = false // Reset loading when the coroutine finishes
            }
        }, enabled = !loading) {
            Text("Start loading")
        }

        if (loading) {
            LinearProgressIndicator(
                progress = { currentProgress },
                modifier = Modifier.fillMaxWidth(),
            )
        }
    }
}

/** Iterate the progress value */
suspend fun loadProgress(updateProgress: (Float) -> Unit) {
    for (i in 1..100) {
        updateProgress(i.toFloat() / 100)
        delay(100)
    }
}
ProgressIndicator.kt

Cuando la carga se completa parcialmente, el indicador lineal del ejemplo anterior aparece de la siguiente manera:

Del mismo modo, el indicador circular aparece de la siguiente manera:

Indicadores indeterminados

Un indicador indeterminado no refleja qué tan cerca está de completarse una operación. En cambio, usa el movimiento para indicarle al usuario que el procesamiento está en curso, aunque sin especificar ningún grado de finalización.

Para crear un indicador de progreso indeterminado, usa el elemento LinearProgressIndicator o CircularProgressIndicator componible, pero no pases un valor para progress. En el siguiente ejemplo, se muestra cómo puedes alternar un indicador indeterminado con la presión de un botón.

@Composable
fun IndeterminateCircularIndicator() {
    var loading by remember { mutableStateOf(false) }

    Button(onClick = { loading = true }, enabled = !loading) {
        Text("Start loading")
    }

    if (!loading) return

    CircularProgressIndicator(
        modifier = Modifier.width(64.dp),
        color = MaterialTheme.colorScheme.secondary,
        trackColor = MaterialTheme.colorScheme.surfaceVariant,
    )
}
ProgressIndicator.kt

A continuación, se muestra un ejemplo de esta implementación cuando el indicador está activo:

A continuación, se muestra un ejemplo de la misma implementación, pero con LinearProgressIndicator en lugar de CircularProgressIndicator.

Recursos adicionales