تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يعمل العنصر القابل للتجميع Card كحاوية لتصميم Material لواجهة المستخدم.
تقدّم البطاقات محتوى واحدًا مترابطًا، مثل:
منتج في تطبيق تسوّق
مقالة إخبارية في تطبيق أخبار
رسالة في تطبيق تواصل
يُميّز التركيز على عرض قطعة محتوى واحدة
Card عن الحاويات الأخرى. على سبيل المثال، يقدّم Scaffold بنية عامة
لشاشة كاملة. "البطاقة" هي عنصر أصغر لواجهة المستخدم داخل تخطيط أكبر، في حين أنّ عنصر التخطيط مثل Column أو Row يقدّم واجهة برمجة تطبيقات أبسط
وأكثر عمومية.
يوضّح لك هذا الموضوع كيفية تنفيذ أربعة أنواع من البطاقات:
يتطلّب هذا التنفيذ ضبط الحد الأدنى من إصدار حزمة SDK لمشروعك على المستوى 21 من واجهة برمجة التطبيقات أو
إصدار أحدث.
التبعيات
إنشاء بطاقة أساسية
تتصرف Card بشكلٍ مشابه للحاويات الأخرى في ميزة "الإنشاء". يمكنك الإفصاح عن محتوى العنصر من خلال
استدعاء عناصر قابلة للتجميع أخرى فيه. على سبيل المثال، لاحظ كيف يحتوي Card على
طلب Text في المثال البسيط التالي:
إنشاء بطاقة مملوءة
يكمن المفتاح هنا في استخدام السمة colors لتغيير
اللون المعبّأ:
النتائج
الشكل 1. مثال على بطاقة تم ملؤها
إنشاء بطاقة مميزة
يوضّح المقتطف التالي كيفية تنفيذ بطاقة مرتفعة. استخدِم العنصر القابل للتجميع المخصّص ElevatedCard.
يمكنك استخدام السمة elevation للتحكّم في مظهر الارتفاع
والظل الناتج.
النتائج
الشكل 2. مثال على بطاقة مرتفعة
إنشاء بطاقة مخطَّطة
في ما يلي مثال على بطاقة مخطّطة. استخدِم العنصر القابل للتجميع المخصّص
OutlinedCard.
النتائج
الشكل 3. مثال على بطاقة مخطّطة
النقاط الرئيسية
اطّلِع على المرجع لتعريف Card في واجهة برمجة التطبيقات. ويحدّد العديد من
المَعلمات التي يمكنك استخدامها لتخصيص مظهر المكوّن وسلوكه.
تشمل بعض المَعلمات الرئيسية ما يلي:
elevation: تُضيف هذه السمة ظلًا إلى المكوّن يجعله يبدو
مرتفعًا فوق الخلفية.
colors: يستخدم النوع CardColors لضبط اللون التلقائي لكل من
الحاوية وأي عناصر فرعية.
enabled: في حال ضبط القيمة false لهذه المَعلمة، ستظهر البطاقة على أنّها
متوقفة ولن تستجيب لإدخالات المستخدِم.
onClick: لا يقبل Card عادةً أحداث النقر. وبناءً على ذلك،
إنّ التحميل الزائد الأساسي الذي تريد ملاحظته هو الذي يحدِّد مَعلمة
onClick. استخدِم هذه الوظيفة الزائدة عندما تريد أن يستجيب
تنفيذك لـ Card للنقرات من المستخدم.
لا تتضمّن البطاقات إجراءات التمرير أو الإغلاق، ولكن يمكن دمجها في
عناصر قابلة للتجميع تتيح هذه الميزات. على سبيل المثال، لتنفيذ ميزة التمرير سريعًا لإغلاق
البطاقة، يمكنك دمجها مع العنصر القابل للتجميع SwipeToDismiss. لدمج
مع التمرير، استخدِم عناصر تعديل التمرير مثل verticalScroll. اطّلِع على مستندات Scroll للحصول على مزيد من المعلومات.
المجموعات التي تتضمّن هذا الدليل
هذا الدليل هو جزء من مجموعات الأدلة السريعة المنظَّمة التي تتناول
أهداف تطوير Android الأوسع نطاقًا:
عرض المكونات التفاعلية
تعرَّف على كيفية استخدام الدوال القابلة للتجميع لإنشاء مكونات جميلة لواجهة المستخدم بسهولة استنادًا إلى نظام التصميم المتعدّد الأبعاد.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-02-06 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-02-06 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Create a card as a container\n\n\u003cbr /\u003e\n\nThe [`Card`](/reference/kotlin/androidx/compose/material3/package-summary#Card(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.material3.CardColors,androidx.compose.material3.CardElevation,androidx.compose.foundation.BorderStroke,kotlin.Function1)) composable acts as a Material Design container for your UI.\nCards present a single coherent piece of content, such as:\n\n- A product in a shopping app.\n- A news story in a news app.\n- A message in a communications app.\n\nThe focus on portraying a single piece of content distinguishes\n`Card` from other containers. For example, `Scaffold` provides general structure\nto a whole screen. Card is a smaller UI element inside a larger\nlayout, whereas a layout component such as `Column` or `Row` provides a simpler\nand more generic API.\n\nThis topic shows you how to implement four types of cards:\n\n- [Basic](#basic)\n- [Filled](#filled)\n- [Elevated](#elevated)\n- [Outlined](#outlined)\n\nVersion compatibility\n---------------------\n\nThis implementation requires that your project minSDK be set to API level 21 or\nhigher.\n\n### Dependencies\n\n### Kotlin\n\n\u003cbr /\u003e\n\n```kotlin\n implementation(platform(\"androidx.compose:compose-bom:2025.08.00\"))\n \n```\n\n\u003cbr /\u003e\n\n### Groovy\n\n\u003cbr /\u003e\n\n```groovy\n implementation platform('androidx.compose:compose-bom:2025.08.00')\n \n```\n\n\u003cbr /\u003e\n\nCreate a basic card\n-------------------\n\n`Card` behaves much like other containers in Compose. You declare its content by\ncalling other composables within it. For example, consider how `Card` contains a\ncall to `Text` in the following minimal example:\n\n @Composable\n fun CardMinimalExample() {\n Card() {\n Text(text = \"Hello, world!\")\n }\n }\n\n| **Note:** By default, a `Card` wraps its content in a `Column` composable, placing each item inside the card beneath one another.\n\nCreate a filled card\n--------------------\n\nThe key here is the use of the `colors` property to change the filled\ncolor:\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun FilledCardExample() {\n Card(\n colors = CardDefaults.cardColors(\n containerColor = MaterialTheme.colorScheme.surfaceVariant,\n ),\n modifier = Modifier\n .size(width = 240.dp, height = 100.dp)\n ) {\n Text(\n text = \"Filled\",\n modifier = Modifier\n .padding(16.dp),\n textAlign = TextAlign.Center,\n )\n }\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Card.kt#L106-L122\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\n**Figure 1.** Example of a filled card.\n\nCreate an elevated card\n-----------------------\n\nThe following snippet demonstrates how to implement an elevated card. Use the\ndedicated [`ElevatedCard`](/reference/kotlin/androidx/compose/material3/package-summary#ElevatedCard(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.material3.CardColors,androidx.compose.material3.CardElevation,kotlin.Function1)) composable.\n\nYou can use the `elevation` property to control the appearance of elevation and\nthe resulting shadow.\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun ElevatedCardExample() {\n ElevatedCard(\n elevation = CardDefaults.cardElevation(\n defaultElevation = 6.dp\n ),\n modifier = Modifier\n .size(width = 240.dp, height = 100.dp)\n ) {\n Text(\n text = \"Elevated\",\n modifier = Modifier\n .padding(16.dp),\n textAlign = TextAlign.Center,\n )\n }\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Card.kt#L85-L101\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\n**Figure 2.** Example of an elevated card.\n\nCreate an outlined card\n-----------------------\n\nThe following is an example of an outlined card. Use the dedicated\n[`OutlinedCard`](/reference/kotlin/androidx/compose/material3/package-summary#OutlinedCard(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.material3.CardColors,androidx.compose.material3.CardElevation,androidx.compose.foundation.BorderStroke,kotlin.Function1)) composable.\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun OutlinedCardExample() {\n OutlinedCard(\n colors = CardDefaults.cardColors(\n containerColor = MaterialTheme.colorScheme.surface,\n ),\n border = BorderStroke(1.dp, Color.Black),\n modifier = Modifier\n .size(width = 240.dp, height = 100.dp)\n ) {\n Text(\n text = \"Outlined\",\n modifier = Modifier\n .padding(16.dp),\n textAlign = TextAlign.Center,\n )\n }\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Card.kt#L127-L144\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\n**Figure 3.** Example of an outlined card.\n\nKey points\n----------\n\nSee the [reference](/reference/kotlin/androidx/compose/material3/package-summary#Card(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.material3.CardColors,androidx.compose.material3.CardElevation,androidx.compose.foundation.BorderStroke,kotlin.Function1)) for the API definition of `Card`. It defines several\nparameters that you can use to customize the appearance and behavior of the\ncomponent.\n\nSome key parameters include:\n\n- **`elevation`**: Adds a shadow to the component that makes it look elevated above the background.\n- **`colors`** : Uses the `CardColors` type to set the default color of both the container and any children.\n- **`enabled`** : If you pass `false` for this parameter, the card appears as disabled and does not respond to user input.\n- **`onClick`** : Ordinarily, a `Card` does not accept click events. As such, the primary overload you would like to note is that which defines an `onClick` parameter. Use this overload when you want your implementation of `Card` to respond to clicks from the user.\n\n| **Beta:** The `Card` overload that defines the `onClick` parameter is experimental.\n\nCards don't come with inherent scroll or dismiss actions, but can integrate into\ncomposables offering these features. For example, to implement swipe to dismiss\non a card, integrate it with the [`SwipeToDismiss`](/reference/kotlin/androidx/compose/material3/package-summary#SwipeToDismiss(androidx.compose.material3.DismissState,kotlin.Function1,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.collections.Set)) composable. To integrate\nwith scroll, use scroll modifiers such as [`verticalScroll`](/reference/kotlin/androidx/compose/foundation/package-summary#(androidx.compose.ui.Modifier).verticalScroll(androidx.compose.foundation.ScrollState,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean)). See the [`Scroll`\ndocumentation](/develop/ui/compose/touch-input/pointer-input/scroll) for more information.\n\nCollections that contain this guide\n-----------------------------------\n\nThis guide is part of these curated Quick Guide collections that cover\nbroader Android development goals: \n\n### Display interactive components\n\nLearn how composable functions can enable you to easily create beautiful UI components based on the Material Design design system. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/display-interactive-components) \n\nHave questions or feedback\n--------------------------\n\nGo to our frequently asked questions page and learn about quick guides or reach out and let us know your thoughts. \n[Go to FAQ](/quick-guides/faq) [Leave feedback](https://issuetracker.google.com/issues/new?component=1573691&template=1993320)"]]
