Fortschrittsanzeigen

Fortschrittsanzeigen stellen den Status eines Vorgangs visuell dar. Sie verwenden Bewegung, um den Nutzer darauf aufmerksam zu machen, wie weit der Prozess, z. B. das Laden oder Verarbeiten von Daten, fortgeschritten ist. Sie können auch darauf hinweisen, dass eine Verarbeitung stattfindet, ohne dass angegeben wird, wie weit sie fortgeschritten ist.

Sehen wir uns drei Anwendungsfälle an, in denen Sie eine Fortschrittsanzeige verwenden könnten:

  • Inhalte laden: Beim Abrufen von Inhalten aus einem Netzwerk, z. B. beim Laden eines Bildes oder von Daten für ein Nutzerprofil.
  • Datei-Upload: Geben Sie dem Nutzer Feedback dazu, wie lange der Upload dauern könnte.
  • Lange Verarbeitung: Wenn eine App eine große Datenmenge verarbeitet, sollte dem Nutzer angezeigt werden, wie viel der Gesamtmenge bereits verarbeitet wurde.

In Material Design gibt es zwei Arten von Fortschrittsanzeigen:

  • Determiniert: Zeigt genau an, wie viel Fortschritt erzielt wurde.
  • Unbestimmt: Wird kontinuierlich animiert, unabhängig vom Fortschritt.

Ebenso kann eine Fortschrittsanzeige eine der beiden folgenden Formen annehmen:

  • Linear: Ein horizontaler Balken, der sich von links nach rechts füllt.
  • Kreisförmig: Ein Kreis, dessen Strichlänge zunimmt, bis er den gesamten Umfang des Kreises umfasst.
Eine lineare Fortschrittsanzeige neben einer kreisförmigen Fortschrittsanzeige.
Abbildung 1. Die beiden Arten von Fortschrittsanzeigen.

API-Oberfläche

Es gibt mehrere Composables, mit denen Sie Fortschrittsanzeigen erstellen können, die mit Material Design kompatibel sind. Ihre Parameter unterscheiden sich jedoch nicht wesentlich. Zu den wichtigsten Parametern, die Sie berücksichtigen sollten, gehören:

  • progress: Der aktuelle Fortschritt, der von der Anzeige dargestellt wird. Übergeben Sie einen Float zwischen 0.0 und 1.0.
  • color: Die Farbe des eigentlichen Indikators. Das ist der Teil der Komponente, der den Fortschritt widerspiegelt und die Komponente vollständig umfasst, wenn der Fortschritt abgeschlossen ist.
  • trackColor: Die Farbe der Spur, über die der Indikator gezeichnet wird.

M3 – Update zu illustrativen Untertiteln

Material 3 Expressive führt LinearWavyProgressIndicator und CircularWavyProgressIndicator als zusätzliche Optionen neben den standardmäßigen flachen LinearProgressIndicator und CircularProgressIndicator ein. Diese Indikatoren haben einen abgerundeten Stil und Konfigurationen für die Spurhöhe und die Wellenform. Wählen Sie den visuellen Stil aus, der am besten zu Ihrem Produkt passt.

Weitere Informationen zu den M3 Expressive-Updates für Fortschrittsanzeigen finden Sie in den Material Design 3-Richtlinien für Fortschrittsanzeigen.

Abbildung 2. Wellenförmige Formen und variable Spurhöhen der Fortschrittsanzeige von Material 3 Expressive.

Fortschrittsanzeigen haben einen abgerundeten, farbenfrohen Stil und zusätzliche Konfigurationen, darunter eine wellenförmige Form und eine variable Höhe der Spur. Für die Form des Aktivitätsindikators gibt es zwei Optionen: Wellig und Flach.

Gewellt

Wellenförmige Fortschrittsanzeigen sind sowohl in bestimmten als auch in unbestimmten Varianten verfügbar. Sie können ihr Erscheinungsbild mit Wellenparametern anpassen, um ausdrucksstärkere visuelle Elemente zu erhalten.

Abbildung 3. Wellenförmige Fortschrittsanzeigen mit ausdrucksstarken Wellenparametern.

Gewellte lineare Anzeigen erhöhen die Höhe des gesamten Containers.

Es gibt zwei Varianten von wellenförmigen Fortschrittsanzeigen: linear und kreisförmig.

Lineare wellenförmige Fortschrittsanzeige mit bestimmtem Fortschritt

Wenn Sie eine wellenförmige Fortschrittsanzeige verwenden, wird standardmäßig eine Wellengeschwindigkeit angewendet, um eine konstante Wellenbewegung zu erzeugen, auch im Modus „Determinate“. Sie können diese Wellenbewegung deaktivieren, indem Sie 0.dp an waveSpeed übergeben.

Das folgende Snippet zeigt, wie Sie einen bestimmten LinearWavyProgressIndicator implementieren, der von einem Slider gesteuert wird:

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

Unbestimmte lineare wellenförmige Fortschrittsanzeige

Verwende unbestimmte Anzeigen, um zu signalisieren, dass ein Prozess läuft, wenn die Wartezeit unbekannt ist. Das folgende Snippet zeigt, wie ein unbestimmter LinearWavyProgressIndicator implementiert wird:

@Composable
fun IndeterminateLinearWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator() }
}

Kreisförmige, wellenförmige Fortschrittsanzeige mit bestimmtem Wert

Die wellenförmige Form kann längere Prozesse weniger statisch wirken lassen und eignet sich am besten, wenn ein ausdrucksstärkerer Stil angemessen ist. Das folgende Snippet zeigt, wie ein bestimmter CircularWavyProgressIndicator implementiert wird, der von einem Slider gesteuert wird:

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

Unbestimmte kreisförmige wellige Fortschrittsanzeige

Kreisförmige Fortschrittsanzeigen sollten direkt auf dem Container oder der Seite zentriert sein, die geladen wird, z. B. auf einer Schaltfläche oder Karte. Das folgende Snippet zeigt, wie ein unbestimmter CircularWavyProgressIndicator implementiert wird:

@Composable
fun IndeterminateCircularWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularWavyProgressIndicator() }
}

Gleichbleibend

Bestimmte Indikatoren

Ein determinierter Indikator gibt genau an, wie weit eine Aktion abgeschlossen ist. Verwenden Sie entweder die Composables LinearProgressIndicator oder CircularProgressIndicator und übergeben Sie einen Wert für den Parameter progress.

Das folgende Snippet zeigt, wie Sie einen bestimmten LinearProgressIndicator implementieren, der von einem Slider gesteuert wird:

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

Das folgende Snippet zeigt, wie Sie einen bestimmten CircularProgressIndicator implementieren, der von einem Slider gesteuert wird:

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

Das folgende Snippet enthält ein relativ detailliertes Beispiel. Wenn der Nutzer auf die Schaltfläche klickt, wird sie in der App durch die Fortschrittsanzeige ersetzt und eine Koroutine gestartet, die den Wert von progress schrittweise erhöht. Dadurch wird die Fortschrittsanzeige schrittweise erhöht.

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

Wenn der Ladevorgang teilweise abgeschlossen ist, wird die lineare Anzeige im vorherigen Beispiel so dargestellt:

Abbildung 4. Eine lineare Fortschrittsanzeige mit bestimmtem Wert.

Die kreisförmige Anzeige sieht so aus:

Abbildung 5. Eine kreisförmige Fortschrittsanzeige mit bestimmtem Fortschritt.

Unbestimmte Anzeigen

Eine unbestimmte Anzeige gibt nicht an, wie weit ein Vorgang abgeschlossen ist. Stattdessen wird dem Nutzer durch Bewegung angezeigt, dass die Verarbeitung läuft, ohne dass der Grad der Fertigstellung angegeben wird.

Wenn Sie eine unbestimmte Fortschrittsanzeige erstellen möchten, verwenden Sie das Composable LinearProgressIndicator oder CircularProgressIndicator, übergeben Sie aber keinen Wert für progress. Das folgende Snippet zeigt, wie ein unbestimmter LinearProgressIndicator implementiert wird:

@Composable
fun IndeterminateLinearProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearProgressIndicator() }
}

Das folgende Snippet zeigt, wie ein unbestimmter CircularProgressIndicator implementiert wird:

@Composable
fun IndeterminateCircularProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularProgressIndicator() }
}

Das folgende Beispiel zeigt, wie Sie eine unbestimmte Anzeige per Tastendruck ein- und ausschalten können. In diesem Beispiel wird auch gezeigt, wie Sie Werte für die Parameter color und trackColor übergeben können, um das Erscheinungsbild des Indikators anzupassen:

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

Hier ein Beispiel für diese Implementierung, wenn die Anzeige aktiv ist:

Abbildung 6. Eine kreisförmige unbestimmte Fortschrittsanzeige.

Das folgende Beispiel zeigt dieselbe Implementierung, aber mit LinearProgressIndicator anstelle von CircularProgressIndicator:

Abbildung 7. Eine lineare unbestimmte Fortschrittsanzeige.

Zusätzliche Ressourcen