مربّع اختيار

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

علم التشريح

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

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

الولايات

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

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

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

التنفيذ

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