مربّع اختيار

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

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

ملاحظة: يمكنك استخدام مربّعات الاختيار بدلاً من أزرار التبديل أو أزرار الاختيار إذا كان بإمكان المستخدم اختيار عدة خيارات في قائمة.

الشكل

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

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

الحالات

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

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

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

الشكل 1. حالات مربّع الاختيار الثلاث بلا علامة وغير محدّد وتم وضع علامة.

التنفيذ

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

النتيجة

ينتج عن هذا المثال المكوّن التالي عندما يكون بلا علامة:

الشكل 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