الشارات

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

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

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

استخدِم العنصر المركّب 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 { mutableIntStateOf(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 داخل الشارة. في هذه الحالة، يعرض عدد السلع في سلة التسوّق.

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

مراجع إضافية

• ‫Material 3 - الشارات
• BadgedBox
• Badge