تعرض أزرار الرموز الإجراءات التي يمكن للمستخدمين اتّخاذها. يجب أن تستخدم أزرار الأيقونات أيقونة ذات معنى واضح، وعادةً ما تمثل الإجراءات الشائعة أو المستخدمة بشكل متكرر.
هناك نوعان من أزرار الرموز:
- تلقائي: يمكن أن تفتح هذه الأزرار عناصر أخرى، مثل قائمة أو بحث.
- التبديل: يمكن أن تمثّل هذه الأزرار إجراءات ثنائية يمكن تفعيلها أو إيقافها، مثل "المفضّلة" أو "الإشارة المرجعية".
مساحة عرض واجهة برمجة التطبيقات
استخدِم الدالة المركّبة IconButton لتنفيذ أزرار الرموز العادية، وIconToggleButton لزرّ يبدّل بين حالتَي الاختيار وعدم الاختيار. لإنشاء أنماط مرئية مختلفة، مثل الأزرار الممتلئة أو الممتلئة بلون واحد أو المحدّدة، استخدِم FilledIconButton وFilledTonalIconButton وOutlinedIconButton أو الأزرار المقابلة لها التي يمكن تفعيلها أو إيقافها FilledIconToggleButton وFilledTonalIconToggleButton وOutlinedIconToggleButton.
تشمل المَعلمات الرئيسية لـ "IconButton" ما يلي:
-
onClick: دالة lambda يتم تنفيذها عندما ينقر المستخدم على زر الرمز -
enabled: قيمة منطقية تتحكّم في حالة تفعيل الزر. عندما تكون قيمة السمةfalse، لا يستجيب الزر لإدخال المستخدم. -
content: المحتوى المركّب داخل الزر، ويكون عادةًIcon.
تشمل المَعلمات الرئيسية لـ IconToggleButton ما يلي:
-
checked: قيمة منطقية تتحكّم في حالة الزر المحدّد. -
onCheckedChange: دالة lambda يتم تنفيذها عندما ينقر المستخدم على الزر، ما يوفّر حالة جديدة لمربّع الاختيار. -
enabled: قيمة منطقية تتحكّم في حالة تفعيل الزر. عندما تكون قيمة السمةfalse، لا يستجيب الزر لإدخال المستخدم.
مثال أساسي: زر رمز مفتاح التبديل
تتيح أزرار رموز التبديل اختيار إجراء واحد أو إلغاء اختياره، مثل إضافة أو إزالة عناصر من المحتوى المفضَّل. تم تصميم IconToggleButton وأنواعها المختلفة لهذا الغرض.
يوضّح المثال التالي كيفية تنفيذ زر رمز تبديل
يغيّر مظهره بناءً على ما إذا كان محدّدًا أو غير محدّد، من خلال إدارة
الحالة باستخدام IconButton:
@Preview @Composable fun ToggleIconButtonExample() { // isToggled initial value should be read from a view model or persistent storage. var isToggled by rememberSaveable { mutableStateOf(false) } IconButton( onClick = { isToggled = !isToggled } ) { Icon( painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite), contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button." ) } }
النقاط الرئيسية حول الرمز
- تحدّد الدالة المركّبة
ToggleIconButtonExampleعنصرIconButtonيمكن تفعيله أو إيقافه.- تنشئ الدالة
mutableStateOf(false)كائنMutableStateيحتوي على قيمة منطقية، تكون في البدايةfalse. يجعل هذاisToggledعنصر احتفاظ بالحالة، ما يعني أنّ Compose يعيد تركيب واجهة المستخدم كلما تغيّرت قيمتها. - تضمن دالة
rememberSaveableاستمرار حالةisToggledفي جميع تغييرات الضبط، مثل تدوير الشاشة.
- تنشئ الدالة
- تحدِّد دالة
onClickLambda فيIconButtonسلوك الزر عند النقر عليه، حيث يتم تبديل الحالة بينtrueوfalse. - تُحمّل المَعلمة
painterفي الدالة المركّبةIconشرطيًاpainterResourceمختلفًا استنادًا إلى حالةisToggled. يؤدي هذا إلى تغيير المظهر المرئي للرمز.- إذا كانت قيمة
isToggledهيtrue، يتم تحميل رمز القلب الممتلئ القابل للرسم. - إذا كانت قيمة
isToggledهيfalse، يتم تحميل القلب المحدَّد القابل للرسم.
- إذا كانت قيمة
- يتم أيضًا تعديل
contentDescriptionفيIconاستنادًا إلى حالةisToggledلتوفير معلومات مناسبة حول تسهيل الاستخدام.
النتيجة
تعرض الصورة التالية زر رمز التبديل من المقتطف السابق في حالته المحدّدة:
مثال متقدّم: إجراءات متكرّرة عند الضغط
يوضّح هذا القسم كيفية إنشاء أزرار رموز تؤدي إلى تنفيذ إجراء بشكل مستمر أثناء الضغط عليها مع الاستمرار، بدلاً من تنفيذ الإجراء مرة واحدة فقط لكل نقرة.
@Composable fun MomentaryIconButton( unselectedImage: Int, selectedImage: Int, contentDescription: String, modifier: Modifier = Modifier, stepDelay: Long = 100L, // Minimum value is 1L milliseconds. onClick: () -> Unit ) { val interactionSource = remember { MutableInteractionSource() } val isPressed by interactionSource.collectIsPressedAsState() val pressedListener by rememberUpdatedState(onClick) LaunchedEffect(isPressed) { while (isPressed) { delay(stepDelay.coerceIn(1L, Long.MAX_VALUE)) pressedListener() } } IconButton( modifier = modifier, onClick = onClick, interactionSource = interactionSource ) { Icon( painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage), contentDescription = contentDescription, ) } }
النقاط الرئيسية حول الرمز
- تأخذ الدالة
MomentaryIconButtonالمَعلمةunselectedImage: Int، وهي رقم تعريف المورد القابل للرسم الخاص بالرمز عندما لا يتم الضغط على الزر، والمَعلمةselectedImage: Int، وهي رقم تعريف المورد القابل للرسم الخاص بالرمز عندما يتم الضغط على الزر. - ويستخدم
interactionSourceلتتبُّع تفاعلات "الضغط" من المستخدم تحديدًا. - تكون قيمة
isPressedصحيحة عندما يتم الضغط على الزر بشكل نشط وتكون خاطئة في الحالات الأخرى. عندما تكون قيمةisPressedهيtrue، يدخلLaunchedEffectفي حلقة تكرار.- داخل هذه الحلقة، يتم استخدام
delay(معstepDelay) لإنشاء فواصل زمنية بين الإجراءات التي يتم تفعيلها. يضمنcoerceInأن يكون التأخير لمدة 1 مللي ثانية على الأقل لمنع التكرار اللانهائي. - يتم استدعاء
pressedListenerبعد كل تأخير داخل التكرار الحلقي. يؤدي ذلك إلى تكرار الإجراء.
- داخل هذه الحلقة، يتم استخدام
- يستخدم
pressedListenerدالةrememberUpdatedStateلضمان أنّ دالة lambdaonClick(الإجراء المطلوب تنفيذه) هي دائمًا الأحدث من آخر عملية تركيب. - يغيّر
Iconصورته المعروضة بناءً على ما إذا كان الزر مضغوطًا حاليًا أم لا.- إذا كانت قيمة
isPressedصحيحة، يتم عرضselectedImage. - بخلاف ذلك، يتم عرض
unselectedImage.
- إذا كانت قيمة
بعد ذلك، استخدِم هذا MomentaryIconButton في مثال. يوضّح المقتطف التالي زرَّين برموز يتحكّمان في عدّاد:
@Preview() @Composable fun MomentaryIconButtonExample() { var pressedCount by remember { mutableIntStateOf(0) } Row( modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically ) { MomentaryIconButton( unselectedImage = R.drawable.fast_rewind, selectedImage = R.drawable.fast_rewind_filled, stepDelay = 100L, onClick = { pressedCount -= 1 }, contentDescription = "Decrease count button" ) Spacer(modifier = Modifier) Text("advanced by $pressedCount frames") Spacer(modifier = Modifier) MomentaryIconButton( unselectedImage = R.drawable.fast_forward, selectedImage = R.drawable.fast_forward_filled, contentDescription = "Increase count button", stepDelay = 100L, onClick = { pressedCount += 1 } ) } }
النقاط الرئيسية حول الرمز
- تعرض الدالة المركّبة
MomentaryIconButtonExampleعنصرRowيحتوي على مثيلَين منMomentaryIconButtonودالة مركّبةTextلإنشاء واجهة مستخدم لزيادة قيمة العدّاد وخفضها. - ويحتفظ بمتغيّر الحالة القابل للتغيير
pressedCountباستخدامrememberوmutableIntStateOf، ويتم ضبطه على 0. عندما يتغيّرpressedCount، تتم إعادة تركيب أي دوال مركّبة تراقبه (مثل الدالة المركّبةText) لتعكس القيمة الجديدة. - يؤدي النقر على أول
MomentaryIconButtonأو الضغط عليه مع الاستمرار إلى خفضpressedCount. - يزيد
MomentaryIconButtonالثانيpressedCountعند النقر عليه أو الضغط مع الاستمرار. - يستخدم كلا الزرَّين
stepDelayتبلغ 100 ملي ثانية، ما يعني أنّ الإجراءonClickيتكرّر كل 100 ملي ثانية أثناء الضغط مع الاستمرار على الزر.
النتيجة
يعرض الفيديو التالي واجهة المستخدم مع أزرار الرموز والعدّاد:
تحديث M3 Expressive
من خلال تحديث M3 Expressive، تتيح أزرار الرموز خيارات إضافية للحجم والزوايا والعرض، ويمكن تغيير شكلها عند الضغط عليها أو اختيارها. عند وضعها في مجموعات الأزرار القياسية، تتفاعل أزرار الرموز أيضًا مع الأزرار المجاورة عند الضغط عليها.
شكل متحرك
يمكن أن يتغيّر شكل أزرار الرموز عند الضغط عليها، ويمكن أن يتغيّر شكل أزرار الرموز القابلة للتبديل استنادًا إلى حالتها المحدّدة. لتفعيل حركة الشكل،
يجب تمرير IconButtonDefaults.shapes() أو IconButtonDefaults.toggleableShapes() إلى
المَعلمة shapes في IconButton أو IconToggleButton.
أزرار الرموز
يوضّح المقتطف التالي كيفية تنفيذ زر رمز يتحرك شكله عند الضغط عليه:
@Composable fun IconButtonWithAnimatedShapeSample() { IconButton( onClick = { /* doSomething() */ }, shapes = IconButtonDefaults.shapes(), ) { Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description") } }
أزرار الرموز القابلة للتبديل
يوضّح المقتطف التالي كيفية تنفيذ زرّ رمز تبديل يتحرّك شكله استنادًا إلى حالته المحدّدة:
@Composable fun IconToggleButtonWithAnimatedShapeSample() { var checked by remember { mutableStateOf(false) } IconToggleButton( checked = checked, onCheckedChange = { checked = it }, shapes = IconButtonDefaults.toggleableShapes(), ) { if (checked) { Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description") } else { Icon(painter = rememberVectorPainter(AppIcons.Lock), contentDescription = "Localized description") } } }
خيارات الحجم والعرض والشكل
تتوفر أزرار الرموز بأشكال مستديرة ومربعة وخمسة أحجام وثلاثة أبعاد.
لمزيد من المعلومات حول تعديلات M3 Expressive لأزرار الرموز، يُرجى الاطّلاع على إرشادات أزرار الرموز في التصميم المتعدد الأبعاد 3.
هناك خمسة متغيرات لحجم زر الرمز: صغير جدًا، وصغير، ومتوسط، وكبير، وكبير جدًا. يتيح كل حجم ثلاثة خيارات للعرض: موحّد (تلقائي) وضيق وعريض.
تتوفر أزرار الرموز في أشكال دائرية أو مربعة، وتغير أزرار تبديل الرموز شكلها عند الضغط عليها أو تحديدها.
للحصول على إرشادات حول الاختيار بين أشكال الزوايا، يُرجى الاطّلاع على إرشادات أزرار الرموز في التصميم المتعدد الأبعاد 3.