Os indicadores de progresso mostram visualmente o status de uma operação. Eles usam o movimento para chamar a atenção do usuário para o quanto o processo está próximo da conclusão, como carregar ou processar dados. Eles também podem indicar que o processamento está ocorrendo, sem referência a quão perto da conclusão ele pode estar.
Considere estes três casos de uso em que você pode usar um indicador de progresso:
- Carregamento de conteúdo: ao buscar conteúdo de uma rede, como carregar uma imagem ou dados para um perfil de usuário.
- Upload de arquivos: informe ao usuário quanto tempo o upload pode levar.
- Processamento longo: enquanto um app estiver processando uma grande quantidade de dados, informe ao usuário quanto do total foi concluído.
No Material Design, há dois tipos de indicadores de progresso:
- Determinado: mostra exatamente quanto progresso foi feito.
- Indeterminado: anima continuamente, sem considerar o progresso.
Da mesma forma, um indicador de progresso pode assumir uma das duas formas a seguir:
- Linear: uma barra horizontal que é preenchida da esquerda para a direita.
- Circular: um círculo cujo traço aumenta de comprimento até abranger toda a circunferência.
Superfície da API
Embora existam vários elementos que podem ser usados para criar indicadores de progresso consistentes com o Material Design, os parâmetros deles não são muito diferentes. Entre os principais parâmetros que você precisa considerar estão os seguintes:
progress: o progresso atual que o indicador mostra. Transmita umFloatentre0.0e1.0.color: a cor do indicador. Ou seja, a parte do componente que reflete o progresso e que o abrange totalmente quando o progresso é concluído.trackColor: a cor da faixa em que o indicador é desenhado.
Atualização do M3 Expressive
O Material 3 Expressive apresenta LinearWavyProgressIndicator e
CircularWavyProgressIndicator como opções adicionais ao lado dos padrões
LinearProgressIndicator e CircularProgressIndicator. Esses indicadores
têm um estilo arredondado e configurações para altura da faixa e formato de onda.
Escolha o estilo visual que melhor se adapta ao seu produto.
Para mais informações sobre as atualizações do M3 Expressive para indicadores de progresso, consulte as diretrizes de indicadores de progresso do Material Design 3.
Os indicadores de progresso têm um estilo arredondado e colorido, além de outras configurações, como uma forma ondulada e altura de faixa variável. O indicador ativo tem duas opções de formato: ondulado e plano.
Ondulado
Os indicadores de progresso ondulados oferecem variantes determinadas e indeterminadas e permitem personalizar a aparência com parâmetros de onda para visuais mais expressivos.
Os indicadores lineares ondulados aumentam a altura do contêiner geral.
Há duas variantes de indicadores de progresso ondulados: linear e circular.
Indicador de progresso linear ondulado determinado
Por padrão, ao usar um indicador de progresso ondulado, uma velocidade de onda é aplicada para
criar um movimento de onda constante, mesmo no modo determinado. É possível desativar esse movimento
de onda transmitindo 0.dp para waveSpeed.
O snippet abaixo demonstra como implementar um LinearWavyProgressIndicator determinado
controlado por um Slider:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun LinearWavyProgressIndicatorSample() { val sliderState = rememberSliderState(0.1f) val animatedProgress by animateFloatAsState( targetValue = sliderState.value, animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec, ) Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator(progress = { animatedProgress }) Spacer(Modifier.requiredHeight(30.dp)) Text("Set progress:") Slider( state = sliderState, onValueChange = { sliderState.value = it }, modifier = Modifier.width(300.dp), ) } }
Indicador de progresso ondulado linear indeterminado
Use indicadores indeterminados para mostrar que um processo está em andamento quando o tempo de espera é desconhecido. O snippet abaixo demonstra como implementar um
LinearWavyProgressIndicator indeterminado:
@Composable fun IndeterminateLinearWavyProgressIndicatorSample() { Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator() } }
Indicador de progresso ondulado circular determinado
A forma ondulada pode fazer com que processos mais longos pareçam menos estáticos e é mais adequada quando
um estilo mais expressivo é apropriado. O snippet abaixo demonstra como
implementar um CircularWavyProgressIndicator determinado controlado por um
Slider:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun CircularWavyProgressIndicatorSample() { val sliderState = rememberSliderState(0.1f) val animatedProgress by animateFloatAsState( targetValue = sliderState.value, animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec, ) Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularWavyProgressIndicator(progress = { animatedProgress }) Spacer(Modifier.requiredHeight(30.dp)) Text("Set progress:") Slider( state = sliderState, onValueChange = { sliderState.value = it }, modifier = Modifier.width(300.dp), ) } }
Indicador de progresso circular ondulado indeterminado
Os indicadores de progresso circulares precisam ser centralizados diretamente no contêiner ou
na página que está sendo carregada, como um botão ou card. O snippet abaixo
demonstra como implementar um CircularWavyProgressIndicator indeterminado:
@Composable fun IndeterminateCircularWavyProgressIndicatorSample() { Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularWavyProgressIndicator() } }
fixo
Indicadores determinados
Um indicador determinado reflete exatamente o nível de conclusão de uma ação. Use os
combináveis LinearProgressIndicator ou CircularProgressIndicator
e transmita um valor para o parâmetro progress.
O snippet abaixo demonstra como implementar um LinearProgressIndicator determinado
controlado por um Slider:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun LinearProgressIndicatorSample() { val sliderState = rememberSliderState(0.1f) val animatedProgress by animateFloatAsState( targetValue = sliderState.value, animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec, ) Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearProgressIndicator(progress = { animatedProgress }) Spacer(Modifier.requiredHeight(30.dp)) Text("Set progress:") Slider( state = sliderState, onValueChange = { sliderState.value = it }, modifier = Modifier.width(300.dp), ) } }
O snippet abaixo demonstra como implementar um CircularProgressIndicator determinado
controlado por um Slider:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun CircularProgressIndicatorSample() { val sliderState = rememberSliderState(0.1f) val animatedProgress by animateFloatAsState( targetValue = sliderState.value, animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec, ) Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularProgressIndicator(progress = { animatedProgress }) Spacer(Modifier.requiredHeight(30.dp)) Text("Set progress:") Slider( state = sliderState, onValueChange = { sliderState.value = it }, modifier = Modifier.width(300.dp), ) } }
O snippet a seguir mostra um exemplo relativamente detalhado. Quando o usuário
pressiona o botão, o app o substitui pelo indicador de progresso e inicia
uma corrotina que aumenta gradualmente o valor de progress. Isso faz com que o
indicador de progresso seja iterado.
@Composable fun LinearDeterminateIndicator() { var currentProgress by remember { mutableFloatStateOf(0f) } var loading by remember { mutableStateOf(false) } val scope = rememberCoroutineScope() // Create a coroutine scope // Animate between progress updates so the indicator fills smoothly. val animatedProgress by animateFloatAsState( targetValue = currentProgress, animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec, ) if (loading) { LinearProgressIndicator( progress = { animatedProgress }, modifier = Modifier.fillMaxWidth(), ) } else { Button(onClick = { loading = true scope.launch { loadProgress { progress -> currentProgress = progress } loading = false // Reset loading when the coroutine finishes } }) { Text("Start loading") } } } /** Iterate the progress value */ suspend fun loadProgress(updateProgress: (Float) -> Unit) { for (i in 1..100) { updateProgress(i.toFloat() / 100) delay(100) } }
Quando o carregamento está parcialmente concluído, o indicador linear no exemplo anterior aparece da seguinte forma:
Da mesma forma, o indicador circular aparece assim:
Indicadores indeterminados
Um indicador indeterminado não reflete o quão perto de ser concluída uma operação está. Em vez disso, ele usa o movimento para indicar ao usuário que o processamento está em andamento, mas sem especificar o grau de conclusão.
Para criar um indicador de progresso indeterminado, use o elemento combinável LinearProgressIndicator
ou CircularProgressIndicator, mas não transmita um valor para
progress. O snippet abaixo demonstra como implementar um LinearProgressIndicator
indeterminado:
@Composable fun IndeterminateLinearProgressIndicatorSample() { Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearProgressIndicator() } }
O snippet abaixo demonstra como implementar um CircularProgressIndicator
indeterminado:
@Composable fun IndeterminateCircularProgressIndicatorSample() { Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularProgressIndicator() } }
O exemplo a seguir demonstra como alternar um indicador indeterminado
pressionando um botão. Este exemplo também demonstra como transmitir valores para
os parâmetros color e trackColor para personalizar a aparência do
indicador:
@Composable fun IndeterminateCircularIndicator() { var loading by remember { mutableStateOf(false) } if (loading) { CircularProgressIndicator( modifier = Modifier.size(64.dp), color = MaterialTheme.colorScheme.secondary, trackColor = MaterialTheme.colorScheme.surfaceVariant, ) } else { Button(onClick = { loading = true }) { Text("Start loading") } } }
Confira um exemplo dessa implementação quando o indicador está ativo:
Confira um exemplo da mesma implementação, mas com
LinearProgressIndicator em vez de CircularProgressIndicator: