الشارات

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

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

مصادر إضافية