الشارات

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

استخدِم العنصر القابل للتجميع 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