Caixa de seleção

As caixas de seleção permitem que os usuários selecionem um ou mais itens de uma lista. Você pode usar um para permitir que o usuário faça o seguinte:

• Ative ou desative um item.
• Selecione uma das várias opções em uma lista.
• indique que você concorda ou aceita.

Anatomia

Uma caixa de seleção consiste nos seguintes elementos:

• Box: é o contêiner da caixa de seleção.
• Verificar: é o indicador visual que mostra se a caixa de seleção está selecionado ou não.
• Rótulo: é o texto que descreve a caixa de seleção.

Estados

Uma caixa de seleção pode estar em um destes três estados:

• Desmarcada: a caixa de seleção não está marcada. A caixa está vazia.
• Indeterminado: a caixa de seleção está em um estado indeterminado. A caixa contém um traço.
• Selecionada: a caixa de seleção está marcada. A caixa tem uma marca de seleção.

A imagem a seguir demonstra os três estados de uma caixa de seleção.

Implementação

Você pode usar o elemento combinável Checkbox para criar uma caixa de seleção no app. Lembre-se de alguns parâmetros importantes:

• checked: o booleano que captura se a caixa de seleção está marcada ou não. desmarcada.
• onCheckedChange(): a função que o app chama quando o usuário toca no caixa de seleção.

O snippet abaixo demonstra como usar o elemento combinável 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

Explicação

Esse código cria uma caixa de seleção que fica desmarcada inicialmente. Quando o usuário clica na caixa de seleção, a lambda onCheckedChange atualiza o estado checked.

Resultado

Quando desmarcado, este exemplo produz o seguinte componente:

E é assim que a mesma caixa de seleção aparece quando marcada:

Exemplo avançado

Veja a seguir um exemplo mais complexo de como você pode implementar caixas de seleção em seu app. Neste snippet, há uma caixa de seleção pai e uma série de filhos caixas de seleção. Quando o usuário toca na caixa de seleção do familiar responsável, o app marca todas as filhas caixas de seleção.

@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

Explicação

Veja a seguir vários pontos que você deve observar deste exemplo:

• Gerenciamento de estado:
  • childCheckedStates: uma lista de booleanos que usam mutableStateOf() para acompanhar o estado marcado de cada caixa de seleção filho.
  • parentState: um ToggleableState com o valor derivado do caixas de seleção filhas estados.
• Componentes da interface:
  • TriStateCheckbox: é necessário para a caixa de seleção mãe, porque ela tem um parâmetro state que permite defini-lo como indeterminado.
  • Checkbox: usado para cada caixa de seleção filha com o estado vinculado a o elemento correspondente em childCheckedStates.
  • Text: mostra marcadores e mensagens ("Selecionar tudo", "Opção X", "Todas" selecionadas").
• Lógica:
  • O onClick da caixa de seleção pai atualiza todas as caixas filhas para oposto do estado pai atual.
  • O onCheckedChange de cada caixa de seleção filha atualiza o estado correspondente na lista childCheckedStates.
  • O código mostra "All options selected". quando todas as caixas de seleção filhas forem marcada.

Resultado

Este exemplo produz o componente a seguir quando todas as caixas de seleção estão desmarcadas.

Da mesma forma, é assim que o componente aparece quando todas as opções estão marcadas, como quando o usuário toca em "Selecionar tudo":

Quando apenas uma opção está marcada, a caixa de seleção pai exibe o valor indeterminado estado:

Outros recursos

• Caixas de seleção do Material Design