الشارات

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

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

مراجع إضافية