Wskaźniki postępu

Wskaźniki postępu wizualnie przedstawiają stan operacji. Wykorzystywane są ruch aby zwrócić uwagę użytkownika na to, jak blisko zakończenia procesu jest wczytywania lub przetwarzania danych. Mogą też oznaczać, że przetwarzanie trwa bez wskazywania, jak bardzo blisko – do końca.

Weź pod uwagę te 3 przypadki, w których możesz użyć wskaźnika postępu:

  • Wczytywanie treści: podczas pobierania treści z sieci, np. od wczytywania. zdjęcie lub dane w profilu użytkownika.
  • Przesyłanie pliku: informujesz użytkownika o tym, ile czasu może zająć przesyłanie.
  • Długie przetwarzanie: gdy aplikacja przetwarza dużą ilość danych, poinformować użytkownika, jaka część filmu została uzupełniona.

W stylu Material Design występują 2 rodzaje wskaźnika postępu:

  • Określ: pokazuje, jak duży postęp został osiągnięty.
  • Nieokreślony: animacja jest ciągła i nie uwzględnia postępu.

Podobnie wskaźnik postępu może mieć jedną z tych form:

  • Liniowy: poziomy pasek, który wypełnia się od lewej do prawej.
  • Okrągły: okrąg, którego obrys wydłuża się, aż obejmie cały obwód koła.
Liniowy wskaźnik postępu wraz z okrągłym wskaźnikiem postępu.
Rysunek 1. 2 rodzaje wskaźników postępu.

Interfejs API

Chociaż do tworzenia wskaźników postępu zgodnych z Material Design można używać różnych komponentów, ich parametry nie różnią się znacząco. Oto najważniejsze parametry, o których należy pamiętać:

  • progress: bieżący postęp wyświetlany przez wskaźnik. Przekaż wartość Float z zakresu 0.0–1.0.
  • color: kolor rzeczywistego wskaźnika. Jest to część który odzwierciedla postęp i w pełni obejmuje gdy postęp zostanie ukończony.
  • trackColor: kolor ścieżki, na której jest narysowany wskaźnik.

Wskaźniki determinacji

Wskaźnik określający dokładnie odzwierciedla stopień ukończenia działania. Użyj jednej LinearProgressIndicator lub CircularProgressIndicator za pomocą funkcji kompozycyjnych i przekazać wartość parametru progress.

Poniżej znajdziesz stosunkowo szczegółowy przykład. Gdy użytkownik naciśnie przycisk, aplikacja wyświetli wskaźnik postępu i uruchomi coroutine, która stopniowo zwiększa wartość zmiennej progress. Powoduje to, że wskaźnik postępu.

@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

Gdy wczytywanie jest w trakcie, wskaźnik liniowy w poprzednim przykładzie wygląda tak:

Podobnie okrągły wskaźnik wygląda tak:

Nieokreślone wskaźniki

Wskaźnik nieokreślony nie pokazuje, jak blisko zakończenia operacji Wykorzystuje ruch, aby pokazać użytkownikowi, że przetwarzanie trwa, ale bez określania poziomu ukończenia.

Aby utworzyć nieokreślony wskaźnik postępu, użyj komponentu LinearProgressIndicator lub CircularProgressIndicator, ale nie przekazuj wartości parametru progress. Ten przykład pokazuje, jak przełączać nieokreślone naciśnięcie przycisku.

@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

Oto przykład implementacji, gdy wskaźnik jest aktywny:

Poniżej znajduje się przykład takiej samej implementacji, ale z opcją LinearProgressIndicator zamiast CircularProgressIndicator.

Dodatkowe materiały