Symbolschaltflächen

Symbolschaltflächen zeigen Aktionen an, die Nutzer ausführen können. Symbolschaltflächen müssen ein Symbol mit einer klaren Bedeutung verwenden und stehen in der Regel für gängige oder häufig verwendete Aktionen.

Es gibt zwei Arten von Symbolschaltflächen:

  • Standard: Mit diesen Schaltflächen können andere Elemente wie ein Menü oder die Suche geöffnet werden.
  • Umschalten: Diese Buttons können binäre Aktionen darstellen, die ein- oder ausgeschaltet werden können, z. B. „Favorit“ oder „Lesezeichen“.
Fünf Symbolschaltflächen mit verschiedenen Symbolen, z. B. für Einstellungen. Einige sind ausgefüllt, was auf eine Auswahl hinweist, und andere sind umrandet.
Abbildung 1. Symbolschaltflächen; einige sind ausgefüllt (was auf eine Auswahl hinweist) und andere sind umrandet.

API-Oberfläche

Verwenden Sie die komponierbare Funktion IconButton, um Standard-Symbolschaltflächen zu implementieren, und IconToggleButton für eine Schaltfläche, mit der zwischen ausgewähltem und nicht ausgewähltem Zustand gewechselt werden kann. Wenn Sie verschiedene visuelle Stile wie „Ausgefüllt“, „Ausgefüllt mit Farbton“ oder „Umrandet“ erstellen möchten, verwenden Sie FilledIconButton, FilledTonalIconButton und OutlinedIconButton oder die entsprechenden umschaltbaren Varianten FilledIconToggleButton, FilledTonalIconToggleButton und OutlinedIconToggleButton.

Zu den wichtigsten Parametern für IconButton gehören:

  • onClick: Eine Lambda-Funktion, die ausgeführt wird, wenn der Nutzer auf die Symbolschaltfläche tippt.
  • enabled: Ein boolescher Wert, der den Aktivierungsstatus der Schaltfläche steuert. Wenn false, reagiert die Schaltfläche nicht auf Nutzereingaben.
  • content: Der zusammensetzbare Inhalt innerhalb des Buttons, normalerweise ein Icon.

Zu den wichtigsten Parametern für IconToggleButton gehören:

  • checked: Ein boolescher Wert, der den ausgewählten Status des Buttons steuert.
  • onCheckedChange: Eine Lambda-Funktion, die ausgeführt wird, wenn der Nutzer auf die Schaltfläche tippt, und den neuen Status „Ausgewählt“ bereitstellt.
  • enabled: Ein boolescher Wert, der den Aktivierungsstatus der Schaltfläche steuert. Wenn false, reagiert die Schaltfläche nicht auf Nutzereingaben.

Einfaches Beispiel: Symbolschaltfläche zum Ein-/Ausschalten

Mit Ein-/Aus-Symbolschaltflächen können einzelne Optionen aktiviert oder deaktiviert werden, zum Beispiel lassen sich so Elemente in die Favoriten aufnehmen oder daraus entfernen. IconToggleButton und seine Varianten sind für diesen Zweck konzipiert.

Im folgenden Beispiel wird gezeigt, wie Sie eine Umschaltschaltfläche mit Symbol implementieren, die ihr Aussehen je nach Auswahl ändert. Dazu wird der Status mit IconButton verwaltet:

@Preview
@Composable
fun ToggleIconButtonExample() {
    // isToggled initial value should be read from a view model or persistent storage.
    var isToggled by rememberSaveable { mutableStateOf(false) }

    IconButton(
        onClick = { isToggled = !isToggled }
    ) {
        Icon(
            painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite),
            contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button."
        )
    }
}

Wichtige Punkte zum Code

  • Das ToggleIconButtonExample-Composable definiert ein umschaltbares IconButton.
    • mutableStateOf(false) erstellt ein MutableState-Objekt, das einen booleschen Wert enthält, der anfänglich false ist. Dadurch wird isToggled zu einem State Holder, d. h., Compose setzt die UI neu zusammen, wenn sich der Wert ändert.
    • rememberSaveable sorgt dafür, dass der Status von isToggled bei Konfigurationsänderungen wie der Bildschirmdrehung beibehalten wird.
  • Die Lambda-Funktion onClick von IconButton definiert das Verhalten des Buttons, wenn er angeklickt wird. Dabei wird der Status zwischen true und false umgeschaltet.
  • Der Parameter painter des Composables Icon lädt je nach isToggled-Zustand bedingt ein anderes painterResource. Dadurch ändert sich das Erscheinungsbild des Symbols.
    • Wenn isToggled den Wert true hat, wird das ausgefüllte Herz-Drawable geladen.
    • Wenn isToggled den Wert false hat, wird das Drawable für das umrandete Herz geladen.
  • Die contentDescription der Icon wird ebenfalls basierend auf dem isToggled-Status aktualisiert, um entsprechende Informationen zur Barrierefreiheit bereitzustellen.

Ergebnis

Die folgende Abbildung zeigt die Ein/Aus-Schaltfläche aus dem vorherigen Snippet im ausgewählten Zustand:

Abbildung 2. Ein „Favorit“-Umschaltsymbol im ausgewählten Zustand.

Erweitertes Beispiel: Wiederholte Aktionen beim Drücken

In diesem Abschnitt wird gezeigt, wie Sie Symbolschaltflächen erstellen, die eine Aktion kontinuierlich auslösen, während der Nutzer sie gedrückt hält, anstatt sie nur einmal pro Klick auszulösen.

@Composable
fun MomentaryIconButton(
    unselectedImage: Int,
    selectedImage: Int,
    contentDescription: String,
    modifier: Modifier = Modifier,
    stepDelay: Long = 100L, // Minimum value is 1L milliseconds.
    onClick: () -> Unit
) {
    val interactionSource = remember { MutableInteractionSource() }
    val isPressed by interactionSource.collectIsPressedAsState()
    val pressedListener by rememberUpdatedState(onClick)

    LaunchedEffect(isPressed) {
        while (isPressed) {
            delay(stepDelay.coerceIn(1L, Long.MAX_VALUE))
            pressedListener()
        }
    }

    IconButton(
        modifier = modifier,
        onClick = onClick,
        interactionSource = interactionSource
    ) {
        Icon(
            painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage),
            contentDescription = contentDescription,
        )
    }
}

Wichtige Punkte zum Code

  • MomentaryIconButton verwendet unselectedImage: Int, die ID der zeichenfähigen Ressource für das Symbol, wenn die Schaltfläche nicht gedrückt ist, und selectedImage: Int, die ID der zeichenfähigen Ressource für das Symbol, wenn die Schaltfläche gedrückt ist.
  • Es wird ein interactionSource verwendet, um speziell „Drücken“-Interaktionen des Nutzers zu erfassen.
  • isPressed ist „true“, wenn die Taste gerade gedrückt wird, andernfalls „false“. Wenn isPressed den Wert true hat, wird die LaunchedEffect in einer Schleife ausgeführt.
    • In dieser Schleife wird ein delay (mit stepDelay) verwendet, um Pausen zwischen den auslösenden Aktionen zu erstellen. coerceIn sorgt dafür, dass die Verzögerung mindestens 1 ms beträgt, um Endlosschleifen zu verhindern.
    • pressedListener wird nach jeder Verzögerung innerhalb der Schleife aufgerufen. Dadurch wird die Aktion wiederholt.
  • pressedListener verwendet rememberUpdatedState, um sicherzustellen, dass der onClick-Lambda-Ausdruck (die auszuführende Aktion) immer die aktuellste Version aus der neuesten Komposition ist.
  • Das angezeigte Bild des Icon ändert sich je nachdem, ob die Taste gerade gedrückt wird oder nicht.
    • Wenn isPressed „true“ ist, wird selectedImage angezeigt.
    • Andernfalls wird unselectedImage angezeigt.

Verwenden Sie als Nächstes dieses MomentaryIconButton in einem Beispiel. Das folgende Snippet zeigt zwei Symbolschaltflächen, die einen Zähler steuern:

@Preview()
@Composable
fun MomentaryIconButtonExample() {
    var pressedCount by remember { mutableIntStateOf(0) }

    Row(
        modifier = Modifier.fillMaxWidth(),
        verticalAlignment = Alignment.CenterVertically
    ) {
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_rewind,
            selectedImage = R.drawable.fast_rewind_filled,
            stepDelay = 100L,
            onClick = { pressedCount -= 1 },
            contentDescription = "Decrease count button"
        )
        Spacer(modifier = Modifier)
        Text("advanced by $pressedCount frames")
        Spacer(modifier = Modifier)
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_forward,
            selectedImage = R.drawable.fast_forward_filled,
            contentDescription = "Increase count button",
            stepDelay = 100L,
            onClick = { pressedCount += 1 }
        )
    }
}

Wichtige Punkte zum Code

  • Das Composable MomentaryIconButtonExample zeigt ein Row mit zwei MomentaryIconButton-Instanzen und einem Text-Composable an, um eine UI zum Erhöhen und Verringern eines Zählers zu erstellen.
  • Es verwaltet eine veränderliche Zustandsvariable pressedCount mit remember und mutableIntStateOf, die mit 0 initialisiert wird. Wenn sich pressedCount ändert, werden alle Composables, die es beobachten (z. B. das Composable Text), neu zusammengesetzt, um den neuen Wert widerzuspiegeln.
  • Mit dem ersten MomentaryIconButton wird pressedCount verringert, wenn du darauf klickst oder ihn gedrückt hältst.
  • Der zweite MomentaryIconButton erhöht pressedCount, wenn er angeklickt oder gedrückt gehalten wird.
  • Beide Schaltflächen verwenden einen stepDelay von 100 Millisekunden. Das bedeutet, dass die Aktion onClick alle 100 ms wiederholt wird, während eine Schaltfläche gedrückt gehalten wird.

Ergebnis

Das folgende Video zeigt die Benutzeroberfläche mit den Symbolschaltflächen und dem Zähler:

Abbildung 3: Eine Zähler-UI mit zwei Symbolschaltflächen (Plus und Minus), mit denen der Zähler erhöht und verringert wird.

M3 – Update zu illustrativen Untertiteln

Mit dem M3 Expressive-Update unterstützen Symbolschaltflächen zusätzliche Optionen für Größe, Ecken und Breite und können ihre Form ändern, wenn sie gedrückt oder ausgewählt werden. Wenn sie in Standard-Schaltflächengruppen platziert werden, interagieren Symbolschaltflächen beim Drücken auch mit benachbarten Schaltflächen.

Animierte Form

Symbolschaltflächen können ihre Form ändern, wenn sie gedrückt werden. Bei Umschaltflächen kann sich die Form je nach ausgewähltem Status ändern. Wenn Sie die Formanimation aktivieren möchten, übergeben Sie IconButtonDefaults.shapes() oder IconButtonDefaults.toggleableShapes() an den Parameter shapes von IconButton oder IconToggleButton.

Symbolschaltflächen

Zustände des Symbol-Buttons
Abbildung 4: Animation der Form von Symbolschaltflächen in runden und quadratischen Formen.

Das folgende Snippet zeigt, wie Sie eine Symbolschaltfläche implementieren, deren Form sich beim Drücken ändert:

@Composable
fun IconButtonWithAnimatedShapeSample() {
    IconButton(
        onClick = { /* doSomething() */ },
        shapes = IconButtonDefaults.shapes(),
    ) {
        Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
    }
}

Symbolschaltflächen zum Ein-/Ausschalten

Zustände der Symbolschaltfläche zum Ein-/Ausschalten
Abbildung 5. Animation der Form des Ein/Aus-Symbols im ausgewählten und nicht ausgewählten Zustand.

Das folgende Snippet zeigt, wie Sie eine Umschalt-Symbolschaltfläche implementieren, deren Form sich je nach ausgewähltem Status ändert:

@Composable
fun IconToggleButtonWithAnimatedShapeSample() {
    var checked by remember { mutableStateOf(false) }
    IconToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        shapes = IconButtonDefaults.toggleableShapes(),
    ) {
        if (checked) {
            Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
        } else {
            Icon(painter = rememberVectorPainter(AppIcons.Lock), contentDescription = "Localized description")
        }
    }
}

Größen-, Breiten- und Formvarianten

Symbolschaltflächen sind in runder und quadratischer Form, in fünf Größen und in drei Breiten verfügbar.

Beispiele für Größen, Formen und Breiten von Symbolschaltflächen
Abbildung 6: Zu den ausdrucksstarken Funktionen gehören fünf Größen, zwei Formen und drei Breiten.

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

Es gibt fünf Größenvarianten für Symbolschaltflächen: extraklein, klein, mittelgroß, groß und extragroß. Für jede Größe gibt es drei Breitenoptionen: einheitlich (Standard), schmal und breit.

Fünf Zeilen und drei Spalten mit Symbolschaltflächen, die ein Herzsymbol zeigen. Die Zeilen werden immer größer und die drei Spalten haben unterschiedliche Breiten: einheitlich, schmal und breit.
Abbildung 7. Symbolschaltflächen mit fünf Größen und drei Breitenoptionen: einheitlich, schmal und breit.

Symbolschaltflächen sind in runden oder eckigen Varianten verfügbar. Symbolschaltflächen zum Ein-/Ausschalten ändern ihre Form, wenn sie gedrückt oder ausgewählt werden.

Zwei Reihen mit jeweils fünf Symbolschaltflächen mit einem Herzsymbol, die von links nach rechts größer werden. Die obere Reihe hat abgerundete Ecken und die untere Reihe hat eckige Ecken.
Abbildung 8. Symbolschaltflächen sind mit runden oder eckigen Ecken verfügbar.

Informationen zur Auswahl zwischen den Eckvarianten finden Sie in den Material Design 3-Richtlinien für Symbolschaltflächen.

Zusätzliche Ressourcen