بطاقة

تعمل وحدة 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. اطّلِع على مستندات التمرير للحصول على مزيد من المعلومات.

مراجع إضافية