بطاقة

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

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

إنّ التركيز على عرض قطعة محتوى واحدة هو ما يميز 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

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

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

مصادر إضافية