بطاقة

يعمل العنصر القابل للإنشاء 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,
        )
    }
}
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. راجِع مستندات التمرير للحصول على مزيد من المعلومات.

مصادر إضافية