بطاقة

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

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

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

بطاقة مرتفعة تتضمّن نصًا ورموزًا
الشكل 1. مثال على بطاقة تتضمّن نصًا ورموزًا

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

تعمل Card بشكل مشابه للحاويات الأخرى في Compose. يمكنك تحديد محتواها من خلال استدعاء دوال مركّبة أخرى داخلها. على سبيل المثال، لنفترض أنّ 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,
        )
    }
}

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

يتم ملء البطاقة بلون السطح المتغيّر من تخصيص التصميم المتعدد الأبعاد.
الشكل 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,
        )
    }
}

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

تظهر بطاقة بارزة فوق خلفية التطبيق مع ظل.
الشكل 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,
        )
    }
}

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

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

القيود

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

مراجع إضافية