زر اختيار

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

الشكل 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.
  • تعدِّل دالة onClick Lambda الحالة selectedOption إلى الخيار الذي تم النقر عليه عند النقر على Row.
  • يُعلم role = Role.RadioButton خدمات تسهيل الاستخدام بأنّ Row يعمل كزر اختيار.
• ينشئ RadioButton(...) الدالة المركّبة RadioButton.
  • يؤدي استخدام onClick = null على RadioButton إلى تحسين أدوات تسهيل الاستخدام. يمنع هذا الإجراء زر الاختيار من معالجة الحدث الناتج عن النقر مباشرةً، ويسمح لمعدِّل selectable في Row بإدارة حالة الاختيار وسلوك أدوات تسهيل الاستخدام.

النتيجة

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

مراجع إضافية

• التصميم المتعدد الأبعاد: الأزرار