الشارات

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

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

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

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