مربّع اختيار

تتيح مربّعات الاختيار للمستخدمين اختيار عنصر واحد أو أكثر من القائمة. يمكنك استخدام مربّع اختيار للسماح للمستخدم بإجراء ما يلي:

• فعِّل عنصرًا أو أوقِفه.
• الاختيار من بين خيارات متعدّدة في قائمة
• الإشارة إلى الموافقة أو القبول

البنية

يتألف مربّع الاختيار من العناصر التالية:

• المربّع: هو الحاوية التي تضمّ مربّع الاختيار.
• مربّع الاختيار: هذا هو المؤشر المرئي الذي يوضّح ما إذا كان مربّع الاختيار محدّدًا أم لا.
• التصنيف: هو النص الذي يصف مربّع الاختيار.

الحالات

يمكن أن تكون خانة الاختيار في إحدى الحالات الثلاث التالية:

• بلا علامة: لم يتم وضع علامة في مربّع الاختيار. المربّع فارغ.
• غير محدّد: يكون مربع الاختيار في حالة غير محدّدة. يحتوي المربّع على شرطة.
• تم وضع علامة: تم وضع علامة في مربّع الاختيار. يحتوي المربّع على علامة اختيار.

توضّح الصورة التالية حالات مربّع الاختيار الثلاث.

التنفيذ

يمكنك استخدام العنصر Checkbox القابل للإنشاء لإنشاء مربّع اختيار في تطبيقك. هناك بضع مَعلمات رئيسية يجب وضعها في الاعتبار:

• ‫checked: القيمة المنطقية التي تحدّد ما إذا كان مربّع الاختيار محدّدًا أم لا.
• onCheckedChange(): الدالة التي يستدعيها التطبيق عندما ينقر المستخدم على مربّع الاختيار.

يوضّح المقتطف التالي كيفية استخدام الدالة البرمجية القابلة للإنشاء 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

الشرح

تنشئ هذه التعليمات البرمجية مربّع اختيار غير محدّد في البداية. عندما ينقر المستخدم على مربّع الاختيار، تعدِّل دالة onCheckedChange Lambda الحالة checked.

النتيجة

ينتج عن هذا المثال المكوّن التالي عند إلغاء تحديده:

وهذه هي الطريقة التي يظهر بها مربّع الاختيار نفسه عند وضع علامة فيه:

مثال متقدّم

في ما يلي مثال أكثر تعقيدًا على كيفية تنفيذ مربّعات الاختيار في تطبيقك. في هذا المقتطف، هناك مربّع اختيار رئيسي وسلسلة من مربّعات الاختيار الفرعية. عندما ينقر المستخدم على مربّع الاختيار الرئيسي، يضع التطبيق علامة في جميع مربّعات الاختيار الثانوية.

@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" عندما تكون جميع مربّعات الاختيار الثانوية محدّدة.

النتيجة

ينتج هذا المثال المكوّن التالي عندما تتم إزالة العلامة من جميع مربّعات الاختيار.

وبالمثل، يظهر المكوّن على النحو التالي عندما يتم تحديد جميع الخيارات، كما يحدث عندما ينقر المستخدم على "اختيار الكل":

عند وضع علامة في مربّع خيار واحد فقط، يعرض مربّع الخيار الرئيسي الحالة غير المحدّدة:

مراجع إضافية

• مربّعات الاختيار في Material Design