الشارات

استخدِم شارة لعرض عنصر مرئي صغير للإشارة إلى الحالة أو قيمة رقمية في عنصر آخر قابل للإنشاء. في ما يلي بعض السيناريوهات الشائعة التي قد تستخدم فيها شارة:

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

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

استخدِم العنصر القابل للتجميع BadgedBox لتطبيق الشارات في تطبيقك. وهو في نهاية المطاف حاوية. ويمكنك التحكّم في مظهره باستخدام المَعلمتَين التاليتَين:

• content: المحتوى القابل للتجميع الذي يحتوي عليه BadgedBox عادةً Icon.
• badge: العنصر القابل للتجميع الذي يظهر كشارة فوق المحتوى عادةً ما تكون Badge المخصّصة قابلة للتجميع.

مثال أساسي

يعرض مقتطف الرمز هذا تنفيذًا أساسيًا BadgedBox:

@Composable
fun BadgeExample() {
    BadgedBox(
        badge = {
            Badge()
        }
    ) {
        Icon(
            imageVector = Icons.Filled.Mail,
            contentDescription = "Email"
        )
    }
}
Badges.kt

يعرض هذا المثال شارة تتداخل مع العنصر القابل للإنشاء Icon المقدَّم. يُرجى ملاحظة ما يلي في الرمز:

• تُستخدَم BadgedBox كسمة حاوية عامة.
• الوسيطة للمَعلمة badge في BadgedBox هي Badge. وبما أنّ Badge لا يحتوي على وسيطات خاصة به، يعرض التطبيق الشارة الافتراضية، وهي دائرة صغيرة حمراء.
• يُستخدَم Icon كوسيطة للمَعلمة content في BadgedBox. وهو الرمز الذي تظهر عليه الشارة. في هذه الحالة، يكون رمز البريد الإلكتروني.

إليك كيفية ظهوره:

مثال مفصّل

يوضّح المقتطف التالي كيفية عرض قيم في الشارة تتغيّر استجابةً لإجراءات المستخدم.

@Composable
fun BadgeInteractiveExample() {
    var itemCount by remember { mutableStateOf(0) }

    Column(
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        BadgedBox(
            badge = {
                if (itemCount > 0) {
                    Badge(
                        containerColor = Color.Red,
                        contentColor = Color.White
                    ) {
                        Text("$itemCount")
                    }
                }
            }
        ) {
            Icon(
                imageVector = Icons.Filled.ShoppingCart,
                contentDescription = "Shopping cart",
            )
        }
        Button(onClick = { itemCount++ }) {
            Text("Add item")
        }
    }
}
Badges.kt

ينفِّذ هذا المثال رمز سلة تسوّق مع شارة تعرِض عدد السلع في سلة التسوّق الخاصة بالمستخدم.

• لا يظهر الرمز BadgedBox إلا عندما يكون عدد العناصر أكبر من 0.
• تتحكّم الوسيطات الخاصة بكلّ من containerColor وcontentColor في شكل الشارة.
• يظهر العنصر Text القابل للإنشاء في خانة المحتوى Badge داخل الشارة. في هذه الحالة، يتم عرض عدد السلع في سلة التسوّق.

تظهر طريقة التنفيذ هذه على النحو التالي:

مصادر إضافية

• المادة 3 - الشارات
• BadgedBox
• Badge