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 più 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 è possibile selezionare più opzioni da un elenco

Anatomia

Una casella di controllo è costituita dai seguenti elementi:

• Casella: il contenitore della casella di controllo.
• Spunta: è 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ò essere in uno dei tre stati seguenti:

• Non selezionata: la casella di controllo non è selezionata. La casella è vuota.
• Indeterminato: la casella di controllo è in uno stato indeterminato. La casella contiene un trattino.
• Selezionato: 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. Non selezionate, indeterminate e selezionate.

Implementazione

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

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

Lo snippet seguente 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 lambda onCheckedChange aggiorna lo stato checked.

Risultato

Se non è selezionata, questo esempio genera il seguente componente:

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 tenere presenti in questo esempio:

• Gestione dello stato:
  • childCheckedStates: un elenco di valori booleani che utilizzano mutableStateOf() per monitorare lo stato di attivazione di ogni casella di controllo secondaria.
  • parentState: un ToggleableState il cui valore deriva dagli stati delle caselle di controllo secondarie.
• Componenti dell'interfaccia utente:
  • 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: vengono visualizzate etichette e messaggi ("Seleziona tutto", "Opzione X", "Tutte le opzioni selezionate").
• Logica:
  • La casella di controllo onClick della casella di controllo principale aggiorna tutte le caselle di controllo secondarie al posto dello stato principale corrente.
  • onCheckedChange di ogni casella di controllo secondaria aggiorna lo stato corrispondente nell'elenco childCheckedStates.
  • Il codice mostra "All options selected" quando tutte le caselle di controllo secondarie sono selezionate.

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

Risultato

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

Figura 4. Caselle di controllo deselezionate

Allo stesso modo, il componente viene visualizzato quando tutte le opzioni sono selezionate, come 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