الشارات

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

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

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

استخدِم الدالة المركّبة BadgedBox لتنفيذ الشارات في تطبيقك. وهي في النهاية عبارة عن حاوية. يمكنك التحكّم في مظهره باستخدام هذين المَعلمتَين الرئيسيتَين:

  • content: المحتوى القابل للإنشاء الذي يحتوي عليه BadgedBox عادةً Icon
  • ‫badge: الدالة المركّبة التي تظهر كشارة فوق المحتوى عادةً ما يكون العنصر المركّب المخصّص Badge.

مثال أساسي

يعرض مقتطف الرمز التالي عملية تنفيذ أساسية لـ BadgedBox:

@Composable
fun BadgeExample() {
    BadgedBox(
        badge = {
            Badge()
        }
    ) {
        Icon(
            imageVector = Icons.Filled.Mail,
            contentDescription = "Email"
        )
    }
}

يعرض هذا المثال شارة تتداخل مع الدالة المركّبة 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")
        }
    }
}

ينفّذ هذا المثال رمز سلة تسوّق مع شارة تعرض عدد السلع في سلة المستخدم.

  • لا يظهر BadgedBox إلا عندما يكون عدد العناصر أكبر من 0.
  • تتحكّم وسيطتا containerColor وcontentColor في مظهر الشارة.
  • يظهر العنصر القابل للإنشاء Text الخاص بفتحة المحتوى Badge ضمن الشارة. في هذه الحالة، يعرض عدد السلع في سلة التسوّق.

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

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

مراجع إضافية