الشارات

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

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

مراجع إضافية