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“.
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. Wennfalse, reagiert die Schaltfläche nicht auf Nutzereingaben.content: Der zusammensetzbare Inhalt innerhalb des Buttons, normalerweise einIcon.
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. Wennfalse, 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 umschaltbaresIconButton.mutableStateOf(false)erstellt einMutableState-Objekt, das einen booleschen Wert enthält, der anfänglichfalseist. Dadurch wirdisToggledzu einem State Holder, d. h., Compose setzt die UI neu zusammen, wenn sich der Wert ändert.rememberSaveablesorgt dafür, dass der Status vonisToggledbei Konfigurationsänderungen wie der Bildschirmdrehung beibehalten wird.
- Die Lambda-Funktion
onClickvonIconButtondefiniert das Verhalten des Buttons, wenn er angeklickt wird. Dabei wird der Status zwischentrueundfalseumgeschaltet. - Der Parameter
painterdes ComposablesIconlädt je nachisToggled-Zustand bedingt ein anderespainterResource. Dadurch ändert sich das Erscheinungsbild des Symbols.- Wenn
isToggledden Werttruehat, wird das ausgefüllte Herz-Drawable geladen. - Wenn
isToggledden Wertfalsehat, wird das Drawable für das umrandete Herz geladen.
- Wenn
- Die
contentDescriptionderIconwird ebenfalls basierend auf demisToggled-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:
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
MomentaryIconButtonverwendetunselectedImage: Int, die ID der zeichenfähigen Ressource für das Symbol, wenn die Schaltfläche nicht gedrückt ist, undselectedImage: Int, die ID der zeichenfähigen Ressource für das Symbol, wenn die Schaltfläche gedrückt ist.- Es wird ein
interactionSourceverwendet, um speziell „Drücken“-Interaktionen des Nutzers zu erfassen. isPressedist „true“, wenn die Taste gerade gedrückt wird, andernfalls „false“. WennisPressedden Werttruehat, wird dieLaunchedEffectin einer Schleife ausgeführt.- In dieser Schleife wird ein
delay(mitstepDelay) verwendet, um Pausen zwischen den auslösenden Aktionen zu erstellen.coerceInsorgt dafür, dass die Verzögerung mindestens 1 ms beträgt, um Endlosschleifen zu verhindern. pressedListenerwird nach jeder Verzögerung innerhalb der Schleife aufgerufen. Dadurch wird die Aktion wiederholt.
- In dieser Schleife wird ein
pressedListenerverwendetrememberUpdatedState, um sicherzustellen, dass deronClick-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, wirdselectedImageangezeigt. - Andernfalls wird
unselectedImageangezeigt.
- Wenn
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
MomentaryIconButtonExamplezeigt einRowmit zweiMomentaryIconButton-Instanzen und einemText-Composable an, um eine UI zum Erhöhen und Verringern eines Zählers zu erstellen. - Es verwaltet eine veränderliche Zustandsvariable
pressedCountmitrememberundmutableIntStateOf, die mit 0 initialisiert wird. Wenn sichpressedCountändert, werden alle Composables, die es beobachten (z. B. das ComposableText), neu zusammengesetzt, um den neuen Wert widerzuspiegeln. - Mit dem ersten
MomentaryIconButtonwirdpressedCountverringert, wenn du darauf klickst oder ihn gedrückt hältst. - Der zweite
MomentaryIconButtonerhöhtpressedCount, wenn er angeklickt oder gedrückt gehalten wird. - Beide Schaltflächen verwenden einen
stepDelayvon 100 Millisekunden. Das bedeutet, dass die AktiononClickalle 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:
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
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
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.
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.
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.
Informationen zur Auswahl zwischen den Eckvarianten finden Sie in den Material Design 3-Richtlinien für Symbolschaltflächen.