Indicadores de progresso

Os indicadores de progresso exibem visualmente o status de uma operação. Eles usam o movimento para mostrar ao usuário se o processo está próximo de concluir o processo, como carregar ou processar dados. Eles também podem indicar que o processamento lugar, sem referência a quão perto ele pode estar de conclusão.

Considere estes três casos de uso em que é possível usar um indicador de progresso:

  • Carregar conteúdo: ao buscar conteúdo de uma rede, como o carregamento uma imagem ou dados para um perfil de usuário.
  • Upload de arquivo: forneça ao usuário um feedback sobre a duração do upload.
  • Processamento longo: enquanto um app processa uma grande quantidade de dados, transmitir ao usuário quanto do total está concluído.

No Material Design, há dois tipos de indicador de progresso:

  • Determinado: exibe exatamente o progresso feito.
  • Indeterminado: a animação é contínua sem considerar o progresso.

Da mesma forma, um indicador de progresso pode assumir uma das duas formas a seguir:

  • Linear: uma barra horizontal que preenche da esquerda para a direita.
  • Circular: um círculo cujo traço cresce em comprimento até abranger o circunferência completa do círculo.
Um indicador de progresso linear ao lado de um circular.
Figura 1. Os dois tipos de indicadores de progresso.

Plataforma da API

Embora existam vários elementos combináveis que podem ser usados para criar indicadores de progresso consistentes com o Material Design, os parâmetros não são muito diferentes. Entre os principais parâmetros que você deve ter em mente são:

  • progress: o progresso atual que o indicador mostra. Transmita um Float entre 0.0 e 1.0.
  • color: a cor do indicador real. Ou seja, a parte componente que reflete o progresso e que abrange totalmente o componente quando o progresso for concluído.
  • trackColor: a cor da faixa em que o indicador é desenhado.

Determinar indicadores

Um indicador determinado reflete exatamente quão completa é uma ação. Use uma destas opções: a LinearProgressIndicator ou a CircularProgressIndicator; combináveis e transmitir um valor para o parâmetro progress.

O snippet a seguir fornece um exemplo relativamente detalhado. Quando o usuário pressionar o botão, o aplicativo exibirá o indicador de progresso e iniciará uma corrotina que aumenta gradualmente o valor de progress. Isso faz com que o indicador de progresso para iterar um por vez.

@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

Quando o carregamento estiver parcialmente concluído, o indicador linear na aparece da seguinte forma:

Da mesma forma, o indicador circular aparece da seguinte maneira:

Indicadores indeterminados

Um indicador indeterminado não reflete o quão perto da conclusão uma operação está o endereço IP interno. Em vez disso, ele usa o movimento para indicar ao usuário que o processamento está em andamento, sem especificar nenhum grau de conclusão.

Para criar um indicador de progresso indeterminado, use o LinearProgressIndicator ou CircularProgressIndicator, mas não transmita um valor para progress O exemplo a seguir demonstra como ativar ou desativar indeterminado ao pressionar um botão.

@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

Confira a seguir um exemplo dessa implementação quando o indicador está ativo:

Veja a seguir um exemplo da mesma implementação, mas com LinearProgressIndicator em vez de CircularProgressIndicator.

Outros recursos