Pulsanti con icone

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".
Cinque pulsanti con icone diverse, ad esempio impostazioni e altro ancora. Alcune sono piene, a indicare la selezione, e altre sono vuote.
Figura 1. Pulsanti icona; alcuni sono pieni (indicano la selezione) e altri sono delineati.

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. Quando false, il pulsante non risponde all'input dell'utente.
  • content: i contenuti componibili all'interno del pulsante, in genere un Icon.

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. Quando false, 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 ToggleIconButtonExample definisce un IconButton attivabile/disattivabile.
    • mutableStateOf(false) crea un oggetto MutableState che contiene un valore booleano, inizialmente false. In questo modo, isToggled diventa un contenitore di stato, il che significa che Compose ricompone la UI ogni volta che il suo valore cambia.
    • rememberSaveable garantisce che lo stato di isToggled persista durante le modifiche alla configurazione, come la rotazione dello schermo.
  • La funzione lambda onClick di IconButton definisce il comportamento del pulsante quando viene fatto clic, alternando lo stato tra true e false.
  • Il parametro painter del composable Icon carica in modo condizionale un painterResource diverso in base allo stato isToggled. 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.
  • Anche l'elemento contentDescription di Icon viene aggiornato in base allo stato di isToggled per fornire informazioni sull'accessibilità appropriate.

Risultato

La seguente immagine mostra il pulsante di attivazione/disattivazione dello snippet precedente nello stato selezionato:

Figura 2. Un pulsante di attivazione/disattivazione "Preferito" 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

  • MomentaryIconButton accetta un unselectedImage: Int, l'ID risorsa drawable per l'icona quando il pulsante non è premuto, e selectedImage: Int, l'ID risorsa drawable per l'icona quando il pulsante è premuto.
  • Utilizza un interactionSource per monitorare in modo specifico le interazioni di "pressione" dell'utente.
  • isPressed è true quando il pulsante viene premuto attivamente e false in caso contrario. Quando isPressed è true, LaunchedEffect entra in un loop.
    • All'interno di questo loop, utilizza un delay (con stepDelay) per creare pause tra le azioni di attivazione. coerceIn garantisce che il ritardo sia di almeno 1 ms per evitare loop infiniti.
    • pressedListener viene richiamato dopo ogni ritardo all'interno del loop. In questo modo, l'azione viene ripetuta.
  • pressedListener utilizza rememberUpdatedState per garantire che la funzione lambda onClick (l'azione da eseguire) sia sempre la più aggiornata dell'ultima composizione.
  • L'immagine visualizzata di Icon cambia a seconda che il pulsante sia premuto o meno.
    • Se isPressed è true, viene mostrato selectedImage.
    • In caso contrario, viene visualizzato unselectedImage.

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 MomentaryIconButtonExample mostra un Row contenente due istanze MomentaryIconButton e un composable Text per creare una UI per incrementare e decrementare un contatore.
  • Mantiene una variabile di stato modificabile pressedCount utilizzando remember e mutableIntStateOf, inizializzata su 0. Quando pressedCount cambia, tutti i composable che lo osservano (come il composable Text) vengono ricomposti per riflettere il nuovo valore.
  • Il primo MomentaryIconButton diminuisce pressedCount quando viene selezionato o tenuto premuto.
  • Il secondo MomentaryIconButton aumenta pressedCount quando viene selezionato o tenuto premuto.
  • Entrambi i pulsanti utilizzano un stepDelay di 100 millisecondi, il che significa che l'azione onClick viene ripetuta ogni 100 ms mentre un pulsante viene tenuto premuto.

Risultato

Il seguente video mostra la UI con i pulsanti icona e il contatore:

Figura 3. Una UI del contatore con due pulsanti icona (più e meno) che incrementano e decrementano 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

Stati del pulsante icona
Figura 4. Animazione della forma del pulsante con icona in forme rotonde e quadrate.

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

Stati del pulsante di attivazione/disattivazione con icona
Figura 5. Attiva/disattiva l'animazione della forma del pulsante con icona negli stati non selezionato e selezionato.

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.

Esempi di dimensioni, forme e larghezze dei pulsanti con icona.
Figura 6. Le caratteristiche espressive includono cinque dimensioni, due forme 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.

Cinque righe e tre colonne di pulsanti con l'icona di un cuore. Ogni riga aumenta di dimensioni e le tre colonne variano in larghezza: uniforme, stretta e larga.
Figura 7. Pulsanti di icone che mostrano cinque dimensioni e tre opzioni di larghezza: uniforme, 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.

Due righe di cinque pulsanti icona con un'icona a forma di cuore, di dimensioni crescenti da sinistra a destra; la riga superiore ha angoli arrotondati e la riga inferiore ha angoli squadrati.
Figura 8. Pulsanti con icone disponibili nelle varianti con angoli arrotondati o squadrati.

Per indicazioni sulla scelta tra le varianti degli angoli, consulta le linee guida per i pulsanti con icona di Material Design 3.

Risorse aggiuntive