Casella di controllo

Le caselle di controllo consentono agli utenti di selezionare uno o più elementi da un elenco. Puoi utilizzare una casella di controllo per consentire all'utente di:

• Attiva o disattiva un elemento.
• Seleziona una delle varie opzioni in un elenco.
• Indica l'accordo o l'accettazione.

Nota: utilizza le caselle di controllo anziché gli interruttori o i pulsanti di opzione se l'utente può selezionare più opzioni in un elenco.

Anatomia

Una casella di controllo è costituita dai seguenti elementi:

• Casella: è il contenitore della casella di controllo.
• Segno di spunta: questo è l'indicatore visivo che mostra se la casella di controllo è selezionata o meno.
• Etichetta: il testo che descrive la casella di controllo.

Stati

Una casella di controllo può avere uno dei tre stati seguenti:

• Deselezionata: la casella di controllo non è selezionata. La casella è vuota.
• Indeterminato: la casella di controllo è in uno stato indeterminato. La casella contiene un trattino.
• Selezionata: la casella di controllo è selezionata. La casella contiene un segno di spunta.

L'immagine seguente mostra i tre stati di una casella di controllo.

Figura 1. I tre stati di una casella di controllo. Deselezionata, indeterminata e selezionata.

Implementazione

Puoi utilizzare il composable Checkbox per creare una casella di controllo nella tua app. Ci sono solo alcuni parametri chiave da tenere a mente:

• checked: il valore booleano che indica se la casella di controllo è selezionata o deselezionata.
• onCheckedChange(): la funzione chiamata dall'app quando l'utente tocca la casella di controllo.

Il seguente snippet mostra come utilizzare il composable Checkbox:

@Composable
fun CheckboxMinimalExample() {
    var checked by remember { mutableStateOf(true) }

    Row(
        verticalAlignment = Alignment.CenterVertically,
    ) {
        Text(
            "Minimal checkbox"
        )
        Checkbox(
            checked = checked,
            onCheckedChange = { checked = it }
        )
    }

    Text(
        if (checked) "Checkbox is checked" else "Checkbox is unchecked"
    )
}
Checkbox.kt

Spiegazione

Questo codice crea una casella di controllo inizialmente deselezionata. Quando l'utente fa clic sulla casella di controllo, la funzione Lambda onCheckedChange aggiorna lo stato checked.

Risultato

Questo esempio produce il seguente componente quando non è selezionato:

Figura 2. Casella di controllo deselezionata

Ecco come appare la stessa casella di controllo quando è selezionata:

Figura 3. Casella di controllo selezionata

Esempio avanzato

Di seguito è riportato un esempio più complesso di come implementare le caselle di controllo nella tua app. In questo snippet, è presente una casella di controllo principale e una serie di caselle di controllo secondarie. Quando l'utente tocca la casella di controllo principale, l'app seleziona tutte le caselle di controllo secondarie.

@Composable
fun CheckboxParentExample() {
    // Initialize states for the child checkboxes
    val childCheckedStates = remember { mutableStateListOf(false, false, false) }

    // Compute the parent state based on children's states
    val parentState = when {
        childCheckedStates.all { it } -> ToggleableState.On
        childCheckedStates.none { it } -> ToggleableState.Off
        else -> ToggleableState.Indeterminate
    }

    Column {
        // Parent TriStateCheckbox
        Row(
            verticalAlignment = Alignment.CenterVertically,
        ) {
            Text("Select all")
            TriStateCheckbox(
                state = parentState,
                onClick = {
                    // Determine new state based on current state
                    val newState = parentState != ToggleableState.On
                    childCheckedStates.forEachIndexed { index, _ ->
                        childCheckedStates[index] = newState
                    }
                }
            )
        }

        // Child Checkboxes
        childCheckedStates.forEachIndexed { index, checked ->
            Row(
                verticalAlignment = Alignment.CenterVertically,
            ) {
                Text("Option ${index + 1}")
                Checkbox(
                    checked = checked,
                    onCheckedChange = { isChecked ->
                        // Update the individual child state
                        childCheckedStates[index] = isChecked
                    }
                )
            }
        }
    }

    if (childCheckedStates.all { it }) {
        Text("All options selected")
    }
}
Checkbox.kt

Spiegazione

Di seguito sono riportati alcuni punti da notare in questo esempio:

• Gestione dello stato:
  • childCheckedStates: un elenco di valori booleani che utilizzano mutableStateOf() per monitorare lo stato di selezione di ogni casella di controllo secondaria.
  • parentState: una ToggleableState il cui valore deriva dagli stati delle caselle di controllo secondarie.
• Componenti UI:
  • TriStateCheckbox: è necessario per la casella di controllo genitore perché ha un parametro state che consente di impostarlo su Indeterminato.
  • Checkbox: utilizzato per ogni casella di controllo secondaria con il relativo stato collegato all'elemento corrispondente in childCheckedStates.
  • Text: mostra etichette e messaggi ("Seleziona tutto", "Opzione X", "Tutte le opzioni selezionate").
• Logica:
  • La casella di controllo principale onClick aggiorna tutte le caselle di controllo secondarie con lo stato opposto a quello attuale della casella di controllo principale.
  • Ogni casella di controllo secondaria onCheckedChange aggiorna lo stato corrispondente nell'elenco childCheckedStates.
  • Il codice visualizza "All options selected" quando tutte le caselle di controllo secondarie sono selezionate.

Nota: se vuoi una casella di controllo con uno stato indeterminato, devi utilizzare TriStateCheckbox. Questo perché ha un parametro state di tipo ToggleableState, mentre Checkbox non lo ha.

Risultato

Questo esempio produce il seguente componente quando tutte le caselle di controllo sono deselezionate.

Figura 4. Caselle di controllo deselezionate

Allo stesso modo, ecco come appare il componente quando tutte le opzioni sono selezionate, ad esempio quando l'utente tocca Seleziona tutto:

Figura 5. Caselle di controllo selezionate

Quando è selezionata una sola opzione, la casella di controllo principale mostra lo stato indeterminato:

Figura 6. Casella di controllo indeterminata

Risorse aggiuntive

• Caselle di controllo Material Design