Pole wyboru

Pola wyboru umożliwiają użytkownikom wybranie co najmniej 1 elementu z listy. Za pomocą pola wyboru możesz zezwolić użytkownikowi na:

  • Włącz lub wyłącz element.
  • Wybierz opcję z listy.
  • Wskaż, czy zgadzasz się na to.

Anatomia

Pole wyboru składa się z tych elementów:

  • Pole: to pole zawiera pole wyboru.
  • Zaznacz: to wizualny wskaźnik pokazujący, czy pole wyboru jest zaznaczone.
  • Etykieta: tekst opisujący pole wyboru.

Stany

Pole wyboru może mieć jeden z 3 stanów:

  • Odznaczone: pole wyboru nie jest zaznaczone. Pudełko jest puste.
  • Nieokreślony: pole wyboru jest w nieokreślonym stanie. Pole zawiera myślnik.
  • Zaznaczone: pole wyboru jest zaznaczone. Pole zawiera znacznik wyboru.

Poniższy obraz przedstawia 3 stany pola wyboru.

Przykład komponentu pola wyboru w 3 stanach: niezaznaczonego, zaznaczonego i nieokreślonego.
Rysunek 1. 3 stany pola wyboru. Odznaczone, nieokreślone i zaznaczone.

Implementacja

Aby utworzyć w aplikacji pole wyboru, możesz użyć komponentu Checkbox. Oto kilka kluczowych parametrów, o których warto pamiętać:

  • checked: wartość logiczna określająca, czy pole wyboru jest zaznaczone, czy nie.
  • onCheckedChange(): funkcja wywoływana przez aplikację, gdy użytkownik kliknie pole wyboru.

Ten fragment kodu pokazuje, jak używać komponentu 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

Wyjaśnienie

Ten kod tworzy pole wyboru, które jest początkowo niezaznaczone. Gdy użytkownik kliknie pole wyboru, funkcja onCheckedChange lambda zaktualizuje stan checked.

Wynik

W tym przykładzie, jeśli nie zaznaczysz pola wyboru, powstanie taki komponent:

Niezaznaczone pole wyboru z etykietą. Pod nim znajduje się tekst „Pole wyboru jest niezaznaczone”.
Rysunek 2. Niezaznaczone pole wyboru

A tak wygląda to samo pole wyboru po zaznaczeniu:

Zaznaczone pole wyboru z etykietą. Pod nim znajduje się tekst „Pole wyboru jest zaznaczone”.
Rysunek 3. Zaznaczone pole wyboru

Przykład zaawansowany

Poniżej znajdziesz bardziej złożony przykład implementacji pól wyboru w aplikacji. W tym fragmencie kodu jest pole wyboru nadrzędne i seria pól wyboru podrzędnych. Gdy użytkownik kliknie pole wyboru rodzica, aplikacja zaznaczy wszystkie pola wyboru podrzędnych.

@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

Wyjaśnienie

Oto kilka informacji, o których warto pamiętać w tym przykładzie:

  • Zarządzanie stanem:
    • childCheckedStates: lista wartości logicznych za pomocą mutableStateOf() do śledzenia stanu zaznaczenia każdego pola wyboru podrzędnego.
    • parentState: parametr ToggleableState, którego wartość pochodzi ze stanów podrzędnych pól wyboru.
  • Składniki interfejsu:
    • TriStateCheckbox: jest wymagane w przypadku pola wyboru rodzica, ponieważ zawiera parametr state, który umożliwia ustawienie go jako nieokreślony.
    • Checkbox: służy do każdego pola wyboru podrzędnego, którego stan jest powiązany z odpowiednim elementem w elementach childCheckedStates.
    • Text: wyświetla etykiety i wiadomości („Zaznacz wszystkie”, „Opcja X”, „Wszystkie opcje zaznaczone”).
  • Logika:
    • Zaznaczenie pola wyboru onClick w elemencie nadrzędnym powoduje zmianę stanu wszystkich pól podrzędnych na przeciwny do stanu elementu nadrzędnego.
    • Pole wyboru onCheckedChange każdego elementu podrzędnego aktualizuje odpowiedni stan na liście childCheckedStates.
    • Gdy wszystkie pola wyboru podrzędnych są zaznaczone, kod wyświetla „All options selected”.

Wynik

W tym przykładzie, gdy wszystkie pola są odznaczone, tworzony jest ten komponent.

Seria niezaznaczonych pól wyboru z etykietą.
Rysunek 4. Odznaczone pola wyboru

Podobnie komponent wygląda, gdy wszystkie opcje są zaznaczone, gdy użytkownik kliknie „Zaznacz wszystkie”:

Seria zaznaczonych pól wyboru z etykietami. Pierwszy z nich jest oznaczony jako „Zaznacz wszystko”. Pod nimi znajduje się element tekstowy z napisem „Wszystkie opcje wybrane”.
Rysunek 5. Zaznaczone pola wyboru

Gdy zaznaczona jest tylko jedna opcja, pole wyboru nadrzędne wyświetla stan nieokreślony:

Seria niezaznaczonych pól wyboru z etykietami. Wszystkie oprócz jednego są odznaczone. Pole wyboru „Zaznacz wszystkie” jest nieokreślone i wyświetla myślnik.
Rysunek 6. Nieokreślone pole wyboru

Dodatkowe materiały