بطاقة

يعمل العنصر القابل للتجميع Card كحاوية لتصميم Material لواجهة المستخدم. تعرض البطاقات عادةً قطعة محتوى واحدة متّسقة. في ما يلي بعض الأمثلة على الحالات التي قد تحتاج فيها إلى استخدام بطاقة:

  • منتج في تطبيق تسوّق
  • قصة إخبارية في تطبيق أخبار
  • رسالة في تطبيق تواصل

إنّ التركيز على عرض قطعة محتوى واحدة هو ما يميز Card عن الحاويات الأخرى. على سبيل المثال، يقدّم Scaffold بنية عامة لشاشة كاملة. "البطاقة" هي بشكل عام عنصر أصغر لواجهة المستخدم داخل تخطيط أكبر، في حين أنّ مكوّن التنسيق مثل Column أو Row يقدّم واجهة برمجة تطبيقات أبسط وأكثر عمومية.

بطاقة بارزة مملوءة بنصوص ورموز
الشكل 1. مثال لبطاقة تمّت تعبئتها بنصوص ورموز

التنفيذ الأساسي

تتصرف Card بشكلٍ مشابه للحاويات الأخرى في ميزة "الإنشاء". يمكنك الإفصاح عن محتوى العنصر من خلال استدعاء عناصر قابلة للتجميع أخرى ضمنه. على سبيل المثال، لاحظ كيف يحتوي Card على طلب Text في المثال البسيط التالي:

@Composable
fun CardMinimalExample() {
    Card() {
        Text(text = "Hello, world!")
    }
}

عمليات التنفيذ المتقدّمة

اطّلِع على المرجع لتعريف Card في واجهة برمجة التطبيقات. ويحدِّد العديد من المَعلمات التي تتيح لك تخصيص مظهر المكوّن وسلوكه.

في ما يلي بعض المَعلمات الرئيسية التي يجب أخذها في الاعتبار:

  • elevation: تُضيف هذه السمة ظلًا إلى المكوّن يجعله يبدو مرتفعًا فوق الخلفية.
  • ‫colors: يستخدم نوع CardColors لضبط اللون التلقائي لكل من الحاوية وأي عناصر فرعية.
  • enabled: في حال ضبط القيمة false لهذه المَعلمة، ستظهر البطاقة على أنّها متوقفة ولن تستجيب لإدخالات المستخدِم.
  • onClick: لا يقبل Card عادةً أحداث النقر. وبناءً على ذلك، إنّ التحميل الزائد الأساسي الذي تريد ملاحظته هو الذي يحدِّد مَعلمة onClick. يجب استخدام هذه الوظيفة الزائدة إذا كنت تريد أن يستجيب تطبيقك لضغطات المستخدم على Card.

يوضّح المثال التالي كيفية استخدام هذه المَعلمات، بالإضافة إلى مَعلمات شائعة أخرى مثل shape وmodifier.

بطاقة مملوءة

في ما يلي مثال على كيفية تنفيذ بطاقة مملوءة.

يكمن المفتاح هنا في استخدام السمة colors لتغيير اللون المعبّأ.

@Composable
fun FilledCardExample() {
    Card(
        colors = CardDefaults.cardColors(
            containerColor = MaterialTheme.colorScheme.surfaceVariant,
        ),
        modifier = Modifier
            .size(width = 240.dp, height = 100.dp)
    ) {
        Text(
            text = "Filled",
            modifier = Modifier
                .padding(16.dp),
            textAlign = TextAlign.Center,
        )
    }
}
Card.kt

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

تم ملء البطاقة بلون متغير السطح من مظهر المواد.
الشكل 2. مثال على بطاقة تم ملؤها

بطاقة بارزة

يوضّح المقتطف التالي كيفية تنفيذ بطاقة مرتفعة. استخدِم العنصر القابل للتجميع المخصّص ElevatedCard.

يمكنك استخدام السمة elevation للتحكّم في مظهر الارتفاع والظل الناتج.

@Composable
fun ElevatedCardExample() {
    ElevatedCard(
        elevation = CardDefaults.cardElevation(
            defaultElevation = 6.dp
        ),
        modifier = Modifier
            .size(width = 240.dp, height = 100.dp)
    ) {
        Text(
            text = "Elevated",
            modifier = Modifier
                .padding(16.dp),
            textAlign = TextAlign.Center,
        )
    }
}
Card.kt

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

تظهر بطاقة فوق خلفية التطبيق مع ظلّ.
الشكل 3. مثال على بطاقة مرتفعة

بطاقة مخطّطة

في ما يلي مثال على بطاقة مخطّطة. استخدِم العنصر القابل للتجميع المخصّص OutlinedCard.

@Composable
fun OutlinedCardExample() {
    OutlinedCard(
        colors = CardDefaults.cardColors(
            containerColor = MaterialTheme.colorScheme.surface,
        ),
        border = BorderStroke(1.dp, Color.Black),
        modifier = Modifier
            .size(width = 240.dp, height = 100.dp)
    ) {
        Text(
            text = "Outlined",
            modifier = Modifier
                .padding(16.dp),
            textAlign = TextAlign.Center,
        )
    }
}
Card.kt

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

يتم تحديد حدود البطاقة بإطار أسود رفيع.
الشكل 4. مثال على بطاقة مخطّطة

القيود

لا تتضمّن البطاقات إجراءات التمرير أو الإغلاق، ولكن يمكن دمجها في عناصر قابلة للتجميع تتيح هذه الميزات. على سبيل المثال، لتنفيذ ميزة التمرير السريع لإغلاق بطاقة، يمكنك دمجها مع العنصر القابل للتجميع SwipeToDismiss. لدمج مع التمرير، استخدِم عناصر تعديل التمرير مثل verticalScroll. يمكنك الاطّلاع على مستندات التمرير للحصول على مزيد من المعلومات.

مصادر إضافية