الانتقال إلى المحتوى الرئيسي

نظرة عامة

يجمع Card المعلومات والإجراءات ذات الصلة ضمن تصدير مُسمّى واحد. ركّب Card.Root وCard.Header وCard.Content وCard.Footer لفصل العنوان والمحتوى والإجراءات الداعمة. لا تدير الأجزاء التحديد أو التركيز أو حالة التطبيق. يمتلك التطبيق سلوك أي عناصر تحكم موضوعة بداخلها.

استخدام

استخدم العنوان بالمستوى الذي تتطلبه الصفحة المحيطة. ضع الإجراءات في الزر أو رابط أصلي حتى يتمكن مستخدمو لوحة المفاتيح والتقنيات المساعدة من تفعيلها.

البنية

استورد Card من twenty-ui/primitives/surfaces. يوفر Card.Root الحد الخارجي والقص، لكنه لا ينشئ أي أقسام داخليًا. لا يتطلب أي جزء جزءًا آخر أو ترتيبًا معينًا للأقسام. تعمل الأقسام أيضًا بصورة مستقلة، دون Card.Root أو سياق. تُعرَض Root وHeader وContent وFooter على شكل div افتراضيًا وتقبل سمات div الأصلية، ومعالجات الأحداث، وclassName، وstyle، ومرجع DOM ref. تُعرَض Action كزر أصلي مع type="button"، وتُعرَض Control كعنصر span. استخدم render مع عنصر أو دالة رد نداء لاختيار هدف دلالي. لا يستنتج أي جزء عنصراً أو دوراً من onClick. يتم تصدير CardRootProps وCardHeaderProps وCardContentProps وCardFooterProps وCardActionProps وCardControlProps من twenty-ui/primitives/surfaces وtwenty-ui/primitives والحزمة الجذرية.

المظهر والفواصل

يملك Card.Root خلفية شفافة افتراضيا. يملأ fullWidth حاويته، ويغيّر backgroundColor الخلفية الخارجية. تملك الأقسام الفرعية خلفياتها الخاصة. يملك Card.Header خلفية أساسية وحشوة وحدا سفليا. يملك Card.Content خلفية ثانوية وحشوة؛ ويضيف divider الاختياري حدا سفليا. يملك Card.Footer خلفية أساسية وحشوة وحدا علويا ما لم يكن divider={false}. تجنب إضافة حدين عند الحد الفاصل نفسه للقسم.

تركيب تفاعلي

اختر زرا أصليا لإجراء ما أو مرساة للتنقل عبر render. وفّر السمات الخاصة بالهدف، مثل type وdisabled وhref وtarget، على ذلك العنصر. يوفّر المالك الفعلي سلوك لوحة المفاتيح والتركيز والتعطيل والروابط الخاص به. لا تضيف Card هذه السلوكيات إلى div للعرض.
زر الإجراء وزر الرفض عنصران شقيقان داخل بطاقة للعرض. لا تضع زرا أو رابطا أو إدخالا أو عنصر تحكم تفاعليا آخر داخل مالك زر أو رابط. عندما يحتوي زر على أجزاء Card، اعرض تلك الأجزاء كعناصر صياغة مثل span.
تحتفظ مالكات الأزرار والروابط الأصلية بتخطيط البطاقة وتحصل على مخطط تركيز مرئي. تُبرز مالكات الأزرار والروابط الصريحة عند التمرير. تحافظ المالكَات المعطلة على مظهرها المعطل. يجب أن توفّر المالكَات المخصصة سلوك التفاعل الخاص بها، بما في ذلك التفعيل بلوحة المفاتيح ومعالجة التعطيل عند الاقتضاء.

إجراءات ممتدة وعناصر تحكم مستقلة

استخدم Card.Action عندما يغطي إجراء أساسي واحد قسمًا من البطاقة يحتوي أيضًا على عناصر تحكم مستقلة. ضع الإجراء مباشرةً داخل Card.Root أو Card.Header أو Card.Content أو Card.Footer. يحدد ذلك الجزء المباشر المنطقة الممتدة. احتفظ بإجراء أساسي واحد لكل منطقة، وأبقِ النماذج الموسعة أو الأقسام المستقلة الأخرى خارجها. يكون Card.Action زرًا أصليًا افتراضيًا. امنح الإجراء الفارغ اسمًا متاحًا باستخدام aria-label أو aria-labelledby، واستخدم aria-describedby للنص الداعم. يحتفظ الرابط الأصلي أو رابط الموجّه المقدَّم عبر render بالتنقل والهدف وسلوك النقر مع مفتاح تعديل والقائمة السياقية الخاصة به. لا تتلقى المكونات المالكة المخصصة دور زر اصطناعيًا أو معالج لوحة مفاتيح أو موضع توقف في التنقل بالزر Tab. ضع السمات الأصلية الخاصة بالهدف على العنصر المعروض. يرفع Card.Control عنصر تحكم مستقلًا أو هدف تلميح أداة فوق الإجراء الممتد. ركّب العنصر الموجود لديه عبر render للاحتفاظ بتخطيطه وسماته. تبقى عناصر التحكم عناصر شقيقة للإجراء الأساسي، بدلًا من أن تكون عناصر تابعة لزر أو رابط. لا تستنتج Card العناصر التابعة التفاعلية ولا تعيد توجيه نقراتها إلى الإجراء الأساسي. تتولى التطبيقات أي معالجة إضافية لازمة للنص العادي المرفوع.
تستخدم مناطق الإجراءات الممكّنة لون التمرير المشترك لـ Card، بما في ذلك عند تمرير مؤشر الماوس فوق عنصر تحكم مستقل. تمتلك منطقة الإجراء المتداخلة تمييزها ولا تميّز عناصرها السلفية. تعرض إجراءات الأزرار والروابط الأصلية مخطط تركيز داخليًا بعرض 2px حول المنطقة الممتدة. يُزال الزر الأصلي المعطّل من التنقل بلوحة المفاتيح، ولا تُميَّز منطقته، بما في ذلك الزر المقدَّم عبر render. تظل الروابط وعناصر التحكم المرتبطة عبر التسميات مسؤولة عن سلوك التعطيل الخاص بها؛ كما أن الخاصية disabled لـ Action تمنع أيضًا معالجة منطقة الإجراء المشتركة. بالنسبة إلى صف Switch أو Radio، اعرض Action باعتباره <label htmlFor={controlId} /> وامنح عنصر التحكم الفعلي ذلك المعرّف. أبقِ تسميته المرئية ووصفه المتاح مرتبطين بعنصر التحكم. لا تنشئ التسمية هدفًا إضافيًا للوحة المفاتيح أو حلقة تركيز. يحتفظ Switch وRadio بسلوك التركيز ولوحة المفاتيح الخاص بهما. ضع النموذج الموسع لخيار radio في Card.Content منفصل بحيث تغطي التسمية رأس التحديد الخاص به فقط.

أجزاء مستقلة وأغلفة مخصصة

يمكن استخدام قسم دون السطح الخارجي. يمكن للأغلفة استخدام نوع الخصائص المصدّر الخاص به ونشره للحفاظ على السمات الأصلية ومعالجات الأحداث والمراجع وتركيب العرض والفئات والأنماط. مع هدف مخصص، ضع المرجع الخاص بالهدف على العنصر الموفّر. تدمج Base UI ذلك المرجع مع مرجع الجزء والخصائص المركبة.

الترحيل

استبدل عمليات الاستيراد الأربع المنفصلة بـ import { Card } from 'twenty-ui/primitives/surfaces'. تصدّر الحزمة الجذرية وtwenty-ui/primitives أيضا كائن Card نفسه. طبّق أسماء الأعضاء نفسها على وسوم JSX والأغلفة المنسقة وأنواع الخصائص. تُزال تصديرات الأجزاء المستقلة دون أسماء مستعارة للتوافق. تبقى خصائص التخطيط وإعدادات التنسيق الافتراضية واستخدام القسم المستقل. استبدل isClickable وhasHoverHighlight بمالك أصلي صريح عبر render. انقل معالجات الإجراءات من الأغلفة المخصصة للعرض فقط، وحافظ على الأسماء المتاحة، وأبق عناصر التحكم المتداخلة خارج الإجراء الأساسي. استخدم render={<button type="button" disabled={disabled} />} لإجراء ما وrender={<a href="/imports" />} للتنقل. تشير مراجع DOM الآن إلى الجزء المعروض فعليا.

الإزاحة

Card.Root

string
CSS background color of the outer card. Child sections have their own backgrounds.
ReactNode
Card sections or other content.
string
CSS class merged with the part class.
boolean
Sets the card width to 100% of its container.
Ref<HTMLDivElement>
Ref to the default div, or the element supplied through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.
CSSProperties
Native styles applied to the rendered part.
"compact" | "default"
افتراضي:"default"
default keeps the standard section appearance. compact uses secondary section backgrounds, 8px header and footer padding, 8px horizontal content padding without vertical padding, and no header divider.

Card.Action

ReactNode
Optional content inside the stretched action. Supply an accessible name for empty actions.
string
CSS class merged with the action class.
boolean
افتراضي:"false"
Disables native button owners and suppresses the action hover treatment. Links and associated controls remain responsible for their own disabled behavior.
Ref<HTMLButtonElement>
Ref to the default button, or the element supplied through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Native element or render callback composed through Base UI useRender. Links retain native navigation and labels activate their associated controls without an additional keyboard target.
CSSProperties
Native styles applied to the rendered action.

Card.Control

ReactNode
Independent controls or tooltip targets lifted above a sibling Card.Action.
string
CSS class merged with the control class.
Ref<HTMLSpanElement>
Ref to the default span, or the element supplied through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Element or render callback composed through Base UI useRender. The supplied control retains its native attributes, events and semantics.
CSSProperties
Native styles applied to the rendered control wrapper.

Card.Header

ReactNode
Header content. Supply a Heading when the title should be a semantic heading.
string
CSS class merged with the part class.
Ref<HTMLDivElement>
Ref to the default div, or the element supplied through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.
CSSProperties
Native styles applied to the rendered part.

Card.Content

ReactNode
Content displayed in the padded body.
string
CSS class merged with the part class.
boolean
Adds a bottom border.
Ref<HTMLDivElement>
Ref to the default div, or the element supplied through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.
CSSProperties
Native styles applied to the rendered part.
Footer content, such as actions or supporting text.
CSS class merged with the part class.
Shows the top border unless explicitly set to false.
Ref to the default div, or the element supplied through render.
Element or render callback composed through Base UI useRender. Supply native button or link attributes on the rendered owner.
Native styles applied to the rendered part.