I pulsanti con icona mostrano le azioni che gli utenti possono intraprendere. I pulsanti con icona devono utilizzare un'icona con un significato chiaro e in genere rappresentano azioni comuni o utilizzate di frequente.
Esistono due tipi di pulsanti icona:
- Predefinito: questi pulsanti possono aprire altri elementi, ad esempio un menu o la ricerca.
- Attivazione/disattivazione: questi pulsanti possono rappresentare azioni binarie che possono essere attivate o disattivate, come "Preferito" o "Segnalibro".
Piattaforma API
Utilizza l'elemento componibile IconButton per implementare i pulsanti icona standard e IconToggleButton per un pulsante che passa dallo stato selezionato a quello non selezionato e viceversa. Per creare stili visivi diversi, come pieno, pieno tonale o con contorno, utilizza FilledIconButton, FilledTonalIconButton e OutlinedIconButton o le relative controparti attivabili/disattivabili FilledIconToggleButton, FilledTonalIconToggleButton e OutlinedIconToggleButton.
I parametri chiave per IconButton includono:
onClick: una funzione lambda che viene eseguita quando l'utente tocca il pulsante con icona.enabled: un valore booleano che controlla lo stato di attivazione del pulsante. Quandofalse, il pulsante non risponde all'input dell'utente.content: i contenuti componibili all'interno del pulsante, in genere unIcon.
I parametri chiave per IconToggleButton includono:
checked: un valore booleano che controlla lo stato selezionato del pulsante.onCheckedChange: una funzione lambda che viene eseguita quando l'utente tocca il pulsante, fornendo il nuovo stato selezionato.enabled: un valore booleano che controlla lo stato di attivazione del pulsante. Quandofalse, il pulsante non risponde all'input dell'utente.
Esempio di base: pulsante icona di attivazione/disattivazione
I pulsanti di attivazione/disattivazione con icona consentono di selezionare o deselezionare una singola scelta, ad esempio
aggiungere o rimuovere un elemento dai preferiti. IconToggleButton e le sue varianti sono progettati per questo scopo.
L'esempio seguente mostra come implementare un pulsante di attivazione/disattivazione con icona che cambia aspetto a seconda che sia selezionato o meno, gestendo lo stato con IconButton:
@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." ) } }
Punti chiave sul codice
- Il componibile
ToggleIconButtonExampledefinisce unIconButtonattivabile/disattivabile.mutableStateOf(false)crea un oggettoMutableStateche contiene un valore booleano, inizialmentefalse. In questo modo,isToggleddiventa un contenitore di stato, il che significa che Compose ricompone la UI ogni volta che il suo valore cambia.rememberSaveablegarantisce che lo stato diisToggledpersista durante le modifiche alla configurazione, come la rotazione dello schermo.
- La funzione lambda
onClickdiIconButtondefinisce il comportamento del pulsante quando viene fatto clic, alternando lo stato tratrueefalse. - Il parametro
painterdel composableIconcarica in modo condizionale unpainterResourcediverso in base allo statoisToggled. In questo modo, l'aspetto visivo dell'icona cambia.- Se
isToggledètrue, carica l'elemento drawable del cuore pieno. - Se
isToggledèfalse, carica l'elemento drawable del cuore con contorno.
- Se
- Anche l'elemento
contentDescriptiondiIconviene aggiornato in base allo stato diisToggledper fornire informazioni sull'accessibilità appropriate.
Risultato
La seguente immagine mostra il pulsante di attivazione/disattivazione dello snippet precedente nello stato selezionato:
Esempio avanzato: azioni ripetute alla pressione
Questa sezione mostra come creare pulsanti con icone che attivano continuamente un'azione mentre l'utente li tiene premuti, anziché attivarla una sola volta per clic.
@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, ) } }
Punti chiave sul codice
MomentaryIconButtonaccetta ununselectedImage: Int, l'ID risorsa drawable per l'icona quando il pulsante non è premuto, eselectedImage: Int, l'ID risorsa drawable per l'icona quando il pulsante è premuto.- Utilizza un
interactionSourceper monitorare in modo specifico le interazioni di "pressione" dell'utente. isPressedè true quando il pulsante viene premuto attivamente e false in caso contrario. QuandoisPressedètrue,LaunchedEffectentra in un loop.- All'interno di questo loop, utilizza un
delay(constepDelay) per creare pause tra le azioni di attivazione.coerceIngarantisce che il ritardo sia di almeno 1 ms per evitare loop infiniti. pressedListenerviene richiamato dopo ogni ritardo all'interno del loop. In questo modo, l'azione viene ripetuta.
- All'interno di questo loop, utilizza un
pressedListenerutilizzarememberUpdatedStateper garantire che la funzione lambdaonClick(l'azione da eseguire) sia sempre la più aggiornata dell'ultima composizione.- L'immagine visualizzata di
Iconcambia a seconda che il pulsante sia premuto o meno.- Se
isPressedè true, viene mostratoselectedImage. - In caso contrario, viene visualizzato
unselectedImage.
- Se
Ora utilizza questo MomentaryIconButton in un esempio. Lo snippet seguente mostra due pulsanti con icone che controllano un contatore:
@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 } ) } }
Punti chiave sul codice
- Il composable
MomentaryIconButtonExamplemostra unRowcontenente due istanzeMomentaryIconButtone un composableTextper creare una UI per incrementare e decrementare un contatore. - Mantiene una variabile di stato modificabile
pressedCountutilizzandorememberemutableIntStateOf, inizializzata su 0. QuandopressedCountcambia, tutti i composable che lo osservano (come il composableText) vengono ricomposti per riflettere il nuovo valore. - Il primo
MomentaryIconButtondiminuiscepressedCountquando viene selezionato o tenuto premuto. - Il secondo
MomentaryIconButtonaumentapressedCountquando viene selezionato o tenuto premuto. - Entrambi i pulsanti utilizzano un
stepDelaydi 100 millisecondi, il che significa che l'azioneonClickviene ripetuta ogni 100 ms mentre un pulsante viene tenuto premuto.
Risultato
Il seguente video mostra la UI con i pulsanti icona e il contatore:
Aggiornamento espressivo M3
Con l'aggiornamento M3 Expressive, i pulsanti con icona supportano opzioni aggiuntive per dimensioni, angoli e larghezza e possono cambiare forma quando vengono premuti o selezionati. Se inseriti in gruppi di pulsanti standard, i pulsanti con icona interagiscono anche con i pulsanti adiacenti quando vengono premuti.
Forma animata
I pulsanti con icona possono animare la loro forma quando vengono premuti, mentre i pulsanti di attivazione/disattivazione con icona possono animare la loro forma in base allo stato di selezione. Per attivare l'animazione della forma,
passa IconButtonDefaults.shapes() o IconButtonDefaults.toggleableShapes() al
parametro shapes di IconButton o IconToggleButton.
Pulsanti icona
Il seguente snippet mostra come implementare un pulsante con icona che anima la sua forma quando viene premuto:
@Composable fun IconButtonWithAnimatedShapeSample() { IconButton( onClick = { /* doSomething() */ }, shapes = IconButtonDefaults.shapes(), ) { Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description") } }
Pulsanti di attivazione/disattivazione delle icone
Il seguente snippet mostra come implementare un pulsante di attivazione/disattivazione con icona che anima la sua forma in base allo stato selezionato:
@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") } } }
Varianti di taglia, larghezza e forma
I pulsanti con icona sono disponibili in forme rotonde e quadrate, cinque dimensioni e tre larghezze.
Per ulteriori informazioni sugli aggiornamenti di M3 Expressive per i pulsanti icona, consulta le linee guida per i pulsanti icona di Material Design 3.
Esistono cinque varianti di dimensioni dei pulsanti con icona: XS, S, M, L e XL. Ogni dimensione supporta tre opzioni di larghezza: uniforme (predefinita), stretta e larga.
I pulsanti con icona sono disponibili nelle varianti con angoli arrotondati o quadrati, mentre i pulsanti con icona di attivazione/disattivazione cambiano forma quando vengono premuti o selezionati.
Per indicazioni sulla scelta tra le varianti degli angoli, consulta le linee guida per i pulsanti con icona di Material Design 3.