الشارات

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

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

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

استخدِم 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. وهو الرمز الذي تظهر عليه الشارة. في هذه الحالة، يكون رمز بريد.

إليك الشكل الذي يظهر به:

شارة بسيطة لا تتضمن أي محتوى
الشكل 2. الحد الأدنى من تنفيذ الشارة

مثال تفصيلي

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

@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. شارة تعرض عدد السلع في سلة التسوّق

مصادر إضافية