بطاقة

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

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

والتركيز على عرض جزء واحد من المحتوى هو ما يميّز 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,
        )
    }
}
Card.kt

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

يتم ملء البطاقة بلون متغير السطح من مظهر Material.
الشكل 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. يمكنك الاطّلاع على مستندات Scroll لمزيد من المعلومات.

مراجع إضافية