الشارات

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

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

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

تنفيذ شارة يتضمّن عدد السلع في سلّة التسوّق
الشكل 3. شارة تعرض عدد السلع في سلّة التسوّق

مراجع إضافية