أزرار الرموز

تعرض أزرار الرموز الإجراءات التي يمكن للمستخدمين اتّخاذها. يجب أن تستخدم أزرار الأيقونات أيقونة ذات معنى واضح، وعادةً ما تمثل الإجراءات الشائعة أو المستخدمة بشكل متكرر.

هناك نوعان من أزرار الرموز:

  • تلقائي: يمكن أن تفتح هذه الأزرار عناصر أخرى، مثل قائمة أو بحث.
  • التبديل: يمكن أن تمثّل هذه الأزرار إجراءات ثنائية يمكن تفعيلها أو إيقافها، مثل "المفضّلة" أو "الإشارة المرجعية".
خمسة أزرار برموز مختلفة، مثل الإعدادات وغيرها بعضها ممتلئ، مما يشير إلى الاختيار، وبعضها محدد.
الشكل 1. أزرار الرموز، بعضها ممتلئ (يشير إلى الاختيار)، والبعض الآخر محدّد.

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

استخدِم الدالة المركّبة 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 في جميع تغييرات الضبط، مثل تدوير الشاشة.
  • تحدِّد دالة onClick Lambda في IconButton سلوك الزر عند النقر عليه، حيث يتم تبديل الحالة بين true وfalse.
  • تُحمّل المَعلمة painter في الدالة المركّبة Icon شرطيًا painterResource مختلفًا استنادًا إلى حالة isToggled. يؤدي هذا إلى تغيير المظهر المرئي للرمز.
    • إذا كانت قيمة isToggled هي true، يتم تحميل رمز القلب الممتلئ القابل للرسم.
    • إذا كانت قيمة isToggled هي false، يتم تحميل القلب المحدَّد القابل للرسم.
  • يتم أيضًا تعديل contentDescription في Icon استنادًا إلى حالة isToggled لتوفير معلومات مناسبة حول تسهيل الاستخدام.

النتيجة

تعرض الصورة التالية زر رمز التبديل من المقتطف السابق في حالته المحدّدة:

الشكل 2. زر تبديل "المفضّلة" في حالته المحدّدة

مثال متقدّم: إجراءات متكرّرة عند الضغط

يوضّح هذا القسم كيفية إنشاء أزرار رموز تؤدي إلى تنفيذ إجراء بشكل مستمر أثناء الضغط عليها مع الاستمرار، بدلاً من تنفيذ الإجراء مرة واحدة فقط لكل نقرة.

@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 لضمان أنّ دالة lambda onClick (الإجراء المطلوب تنفيذه) هي دائمًا الأحدث من آخر عملية تركيب.
  • يغيّر 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 ملي ثانية أثناء الضغط مع الاستمرار على الزر.

النتيجة

يعرض الفيديو التالي واجهة المستخدم مع أزرار الرموز والعدّاد:

الشكل 3. واجهة مستخدم لعدّاد يتضمّن زرَّين (علامة الجمع وعلامة الطرح) لزيادة العدّاد وإنقاصه

تحديث M3 Expressive

من خلال تحديث M3 Expressive، تتيح أزرار الرموز خيارات إضافية للحجم والزوايا والعرض، ويمكن تغيير شكلها عند الضغط عليها أو اختيارها. عند وضعها في مجموعات الأزرار القياسية، تتفاعل أزرار الرموز أيضًا مع الأزرار المجاورة عند الضغط عليها.

شكل متحرك

يمكن أن يتغيّر شكل أزرار الرموز عند الضغط عليها، ويمكن أن يتغيّر شكل أزرار الرموز القابلة للتبديل استنادًا إلى حالتها المحدّدة. لتفعيل حركة الشكل، يجب تمرير IconButtonDefaults.shapes() أو IconButtonDefaults.toggleableShapes() إلى المَعلمة shapes في IconButton أو IconToggleButton.

أزرار الرموز

حالات زر الرمز
الشكل 4. صورة متحركة لشكل زر الرمز بأشكال دائرية ومربّعة

يوضّح المقتطف التالي كيفية تنفيذ زر رمز يتحرك شكله عند الضغط عليه:

@Composable
fun IconButtonWithAnimatedShapeSample() {
    IconButton(
        onClick = { /* doSomething() */ },
        shapes = IconButtonDefaults.shapes(),
    ) {
        Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
    }
}

أزرار الرموز القابلة للتبديل

حالات زر رمز التبديل
الشكل 5. توضّح الصورة المتحركة شكل زر رمز التبديل في حالتَي الاختيار وعدم الاختيار.

يوضّح المقتطف التالي كيفية تنفيذ زرّ رمز تبديل يتحرّك شكله استنادًا إلى حالته المحدّدة:

@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")
        }
    }
}

خيارات الحجم والعرض والشكل

تتوفر أزرار الرموز بأشكال مستديرة ومربعة وخمسة أحجام وثلاثة أبعاد.

أمثلة على أحجام أزرار الرموز وأشكالها وعرضها
الشكل 6: وتشمل الميزات التعبيرية خمسة أحجام وشكلَين وثلاثة عروض.

لمزيد من المعلومات حول تعديلات M3 Expressive لأزرار الرموز، يُرجى الاطّلاع على إرشادات أزرار الرموز في التصميم المتعدد الأبعاد 3.

هناك خمسة متغيرات لحجم زر الرمز: صغير جدًا، وصغير، ومتوسط، وكبير، وكبير جدًا. يتيح كل حجم ثلاثة خيارات للعرض: موحّد (تلقائي) وضيق وعريض.

خمسة صفوف وثلاثة أعمدة من أزرار الرموز التي تعرض رمز قلب يزداد حجم كل صف، وتختلف الأعمدة الثلاثة حسب العرض: موحد وضيق وعريض.
الشكل 7. أزرار رموز تعرض خمسة أحجام وثلاثة خيارات للعرض: موحّد وضيق وعريض

تتوفر أزرار الرموز في أشكال دائرية أو مربعة، وتغير أزرار تبديل الرموز شكلها عند الضغط عليها أو تحديدها.

صفان من خمسة أزرار رموز مع رمز قلب، يزداد حجمها من اليسار إلى اليمين؛ يحتوي الصف العلوي على زوايا مستديرة والصف السفلي به زوايا مربعة.
الشكل 8 تتوفّر أزرار الرموز بأشكال دائرية أو مربّعة.

للحصول على إرشادات حول الاختيار بين أشكال الزوايا، يُرجى الاطّلاع على إرشادات أزرار الرموز في التصميم المتعدد الأبعاد 3.

مراجع إضافية