תיבת סימון

תיבות סימון מאפשרות למשתמשים לבחור פריט אחד או יותר מתוך רשימה. אפשר להשתמש בתיבת סימון כדי לאפשר למשתמשים:

• מפעילים או משביתים פריט.
• לבחור מתוך כמה אפשרויות ברשימה.
• מציינים הסכמה או אישור.

הערה: אם המשתמש יכול לבחור כמה אפשרויות ברשימה, צריך להשתמש בתיבות סימון במקום במתגים או בכפתורי בחירה.

אנטומיה

תיבת סימון מורכבת מהרכיבים הבאים:

• ‫Box: זהו מאגר התוכן של תיבת הסימון.
• תיבת סימון: זהו האינדיקטור הוויזואלי שמראה אם תיבת הסימון מסומנת או לא.
• תווית: הטקסט שמתאר את תיבת הסימון.

מדינות

תיבת סימון יכולה להיות באחד משלושת המצבים הבאים:

• לא מסומנת: תיבת הסימון לא מסומנת. התיבה ריקה.
• לא נקבע: תיבת הסימון במצב לא נקבע. התיבה מכילה מקף.
• נבחר: תיבת הסימון מסומנת. התיבה מכילה סימן וי.

בתמונה הבאה מוצגים שלושת המצבים של תיבת סימון.

איור 1. שלושת המצבים של תיבת סימון. לא נבחר, לא ברור ונבחר.

הטמעה

אפשר להשתמש ב-composable‏ Checkbox כדי ליצור תיבת סימון באפליקציה. יש רק כמה פרמטרים חשובים שכדאי לזכור:

• ‫checked: הערך הבוליאני שמציין אם תיבת הסימון מסומנת או לא.
• ‫onCheckedChange(): הפונקציה שהאפליקציה קוראת לה כשהמשתמש מקיש על תיבת הסימון.

בדוגמה הבאה אפשר לראות איך משתמשים ב-Checkbox composable:

@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

הסבר

הקוד הזה יוצר תיבת סימון שלא מסומנת בהתחלה. כשמשתמש לוחץ על תיבת הסימון, פונקציית ה-lambda‏ onCheckedChange מעדכנת את המצב של checked.

התוצאה

בדוגמה הזו, אם לא מסמנים את התיבה, הרכיב הבא נוצר:

איור 2. תיבת סימון שלא סומנה

וכך נראית אותה תיבת סימון כשהיא מסומנת:

איור 3. תיבת סימון מסומנת

דוגמה מתקדמת

בדוגמה המורכבת הבאה אפשר לראות איך מטמיעים תיבות סימון באפליקציה. בקטע הקוד הזה יש תיבת סימון ראשית וסדרה של תיבות סימון משניות. כשהמשתמש מקיש על תיבת הסימון של הרכיב העליון, האפליקציה מסמנת את כל תיבות הסימון של הרכיבים המשניים.

@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

הסבר

הנה כמה נקודות שחשוב לשים לב אליהן בדוגמה הזו:

• ניהול מצב:
  • ‫childCheckedStates: רשימה של ערכים בוליאניים באמצעות mutableStateOf() כדי לעקוב אחרי מצב הסימון של כל תיבת סימון צאצא.
  • ‫parentState: ToggleableState שהערך שלו נגזר ממצבי תיבות הסימון של רכיבי הבן.
• רכיבי ממשק משתמש:
  • ‫TriStateCheckbox: נדרש לתיבת הסימון של ההורה כי יש לו פרמטר state שמאפשר להגדיר אותו למצב לא מוגדר.
  • ‫Checkbox: משמש לכל תיבת סימון צאצא, כשהמצב שלה מקושר לאלמנט המתאים ב-childCheckedStates.
  • ‫Text: הצגת תוויות והודעות ("בחירת הכול", "אפשרות X", "כל האפשרויות נבחרו").
• לוגיקה:
  • תיבת הסימון של האב onClick מעדכנת את כל תיבות הסימון של הצאצאים למצב ההפוך מהמצב הנוכחי של האב.
  • כל תיבת סימון של צאצא onCheckedChange מעדכנת את המצב התואם שלה ברשימה childCheckedStates.
  • הקוד מציג 'All options selected' כשכל תיבות הסימון של הצאצאים מסומנות.

הערה: אם רוצים להוסיף תיבת סימון עם מצב לא מוגדר, צריך להשתמש ב-TriStateCheckbox. הסיבה לכך היא שהפרמטר state הוא מסוג ToggleableState, ואילו הפרמטר Checkbox לא.

התוצאה

בדוגמה הזו, הרכיב הבא נוצר כשכל תיבות הסימון לא מסומנות.

איור 4. תיבות סימון לא מסומנות

באופן דומה, כך הרכיב נראה כשכל האפשרויות מסומנות, כמו כשמשתמש מקיש על 'בחירת הכל':

איור 5. תיבות סימון מסומנות

אם מסומנת רק אפשרות אחת, תיבת הסימון של ההורה תציג את המצב הלא מוגדר:

איור 6. תיבת סימון במצב לא ידוע

מקורות מידע נוספים

• תיבות סימון ב-Material Design