مربّع اختيار

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

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

علم التشريح

يتكون مربع الاختيار من العناصر التالية:

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

الولايات

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

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

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

التنفيذ

يمكنك استخدام العنصر القابل للتجميع 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