زر اختيار

يتيح زر الاختيار للمستخدم تحديد خيار من مجموعة من الخيارات. يمكنك استخدام زر اختيار عندما يكون من الممكن تحديد عنصر واحد فقط من قائمة. إذا كان على المستخدمين اختيار أكثر من عنصر واحد، استخدِم مفتاح تبديل بدلاً من ذلك.

الشكل 1. زوج من أزرار الاختيار مع تحديد أحد الخيارَين

مساحة واجهة برمجة التطبيقات

استخدِم العنصر القابل للإنشاء RadioButton لإدراج الخيارات المتاحة. لفّ كل RadioButton خيار وتصنيفه داخل مكوّن Row لتجميعها معًا.

تتضمّن RadioButton المَعلمات الرئيسية التالية:

• ‫selected: يشير إلى ما إذا كان زر الاختيار محدّدًا.
• onClick: دالة lambda ينفّذها تطبيقك عندما ينقر المستخدم على زر الاختيار. إذا كانت القيمة null، لا يمكن للمستخدم التفاعل مباشرةً مع زر الاختيار.
• ‫enabled: تتحكّم هذه السمة في ما إذا كان زر الاختيار مفعَّلاً أو غير مفعَّل. لا يمكن للمستخدمين التفاعل مع أزرار الاختيار غير المفعَّلة.
• ‫interactionSource: تتيح لك مراقبة حالة تفاعل الزر، مثلاً، ما إذا تم الضغط عليه أو تمرير مؤشر الماوس فوقه أو التركيز عليه.

إنشاء زر اختيار أساسي

يعرض مقتطف الرمز التالي قائمة بأزرار الاختيار ضمن Column:

@Composable
fun RadioButtonSingleSelection(modifier: Modifier = Modifier) {
    val radioOptions = listOf("Calls", "Missed", "Friends")
    val (selectedOption, onOptionSelected) = remember { mutableStateOf(radioOptions[0]) }
    // Note that Modifier.selectableGroup() is essential to ensure correct accessibility behavior
    Column(modifier.selectableGroup()) {
        radioOptions.forEach { text ->
            Row(
                Modifier
                    .fillMaxWidth()
                    .height(56.dp)
                    .selectable(
                        selected = (text == selectedOption),
                        onClick = { onOptionSelected(text) },
                        role = Role.RadioButton
                    )
                    .padding(horizontal = 16.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                RadioButton(
                    selected = (text == selectedOption),
                    onClick = null // null recommended for accessibility with screen readers
                )
                Text(
                    text = text,
                    style = MaterialTheme.typography.bodyLarge,
                    modifier = Modifier.padding(start = 16.dp)
                )
            }
        }
    }
}
RadioButton.kt

النقاط الرئيسية حول الرمز

• يمثّل radioOptions تصنيفات أزرار الاختيار.
• تنشئ الدالة القابلة للإنشاء remember متغير حالة selectedOption ودالة لتعديل هذه الحالة تُسمى onOptionSelected. تحتوي هذه الحالة على خيار زر الاختيار المحدّد.
  • تعمل mutableStateOf(radioOptions[0]) على تهيئة الحالة إلى العنصر الأول في القائمة. "المكالمات" هي العنصر الأول، لذا يتم تلقائيًا تحديد زر الاختيار الخاص بها.
• يضمن Modifier.selectableGroup() سلوك إمكانية الوصول المناسب لقارئات الشاشة. تُعلم هذه السمة النظام بأنّ العناصر ضِمن Column هي جزء من مجموعة يمكن اختيارها، ما يتيح توفير الدعم المناسب لبرامج قراءة الشاشة.
• تجعل Modifier.selectable() Row بأكمله عنصرًا واحدًا يمكن تحديده.
  • يشير selected إلى ما إذا كان Row الحالي محدّدًا استنادًا إلى حالة selectedOption.
  • تعدِّل دالة Lambda onClick حالة selectedOption إلى الخيار الذي تم النقر عليه عند النقر على Row.
  • يُعلم role = Role.RadioButton خدمات تسهيل الاستخدام بأنّ Row تعمل كزر اختيار.
• تنشئ RadioButton(...) العنصر RadioButton القابل للإنشاء.
  • يؤدي النقر على onClick = null في RadioButton إلى تحسين إمكانية الوصول. يمنع ذلك زر الاختيار من معالجة حدث النقر مباشرةً، ويتيح للمعدِّل selectable في Row إدارة حالة التحديد وسلوك تسهيل الاستخدام.

النتيجة

الشكل 2. ثلاثة أزرار اختيار مع تحديد الخيار "الأصدقاء"

مراجع إضافية

• ‫Material Design: الأزرار