کارت (Card)

معرفی

کارت یک کانتینر انعطاف‌پذیر برای نمایش محتوای مرتبط است.

چه زمانی استفاده کنیم:

• برای گروه‌بندی محتوای مرتبط در یک بخش مجزا
• برای نمایش آیتم‌ها در grid layout
• به عنوان container عمومی برای فرم‌ها، محتوا و اطلاعات

چه زمانی استفاده نکنیم:

• برای نمایش یک عدد یا متریک — از MetricCard یا StatDisplay استفاده کنید
• برای نمایش اطلاعات حساب یا پروفایل — از Account استفاده کنید
• برای مقایسهٔ یک عدد با دورهٔ قبل — از MetricCard با previous و TrendIndicator استفاده کنید

استفاده

زمین بازی

با تغییر تنظیمات زیر، کارت را به صورت زنده مشاهده کنید.

import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@partodata/ui'

<Card variant="default" size="md">
  <CardHeader>
    <CardTitle>عنوان کارت</CardTitle>
    <CardDescription>توضیحات کوتاه درباره محتوای کارت</CardDescription>
  </CardHeader>
  <CardContent>
    <p>محتوای کارت در اینجا قرار می‌گیرد.</p>
  </CardContent>
</Card>

import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, Button } from '@partodata/ui'
;<Card>
  <CardHeader>
    <CardTitle>عنوان کارت</CardTitle>
    <CardDescription>توضیحات کارت</CardDescription>
  </CardHeader>
  <CardContent>
    <p>محتوای اصلی کارت</p>
  </CardContent>
  <CardFooter>
    <Button>عملیات</Button>
  </CardFooter>
</Card>

حالت‌ها و انواع

انواع ظاهری

کارت تعاملی (قابل کلیک)

variant="interactive" یک کارت قابل کلیک است، پس باید با صفحه‌کلید هم قابل استفاده باشد. با asChild کارت روی فرزند خودش رندر می‌شود؛ یک <button> یا <Link> واقعی بدهید تا tab stop، فعال‌سازی با Enter/Space و حلقهٔ focus به‌صورت بومی فراهم شود.

<Card variant="interactive" asChild>
  <button type="button" onClick={openCampaign}>
    <CardHeader>
      <CardTitle>کمپین تخفیف فصلی</CardTitle>
      <CardDescription>برای مشاهدهٔ جزئیات کلیک کنید</CardDescription>
    </CardHeader>
  </button>
</Card>

اندازه‌ها

ساده

کارت کم‌حجم بدون header — مناسب snippet‌های کوتاه و رهنمودهای ثانویه.

با فرم

ترکیب CardHeader + CardContent + CardFooter برای فرم‌های جمع‌وجور (ورود، تنظیمات، dialog محتوایی).

کامپوننت‌ها

Props

Card

CardHeader

CardTitle

CardDescription

CardContent

CardFooter

راهنمای استفاده

دسترسی‌پذیری

• کارت از تگ‌های معنادار HTML استفاده می‌کند
• CardTitle به عنوان heading عمل می‌کند و سلسله‌مراتب صفحه را حفظ می‌کند
• برای کارت‌های تعاملی (قابل کلیک) از variant="interactive" به‌همراه asChild استفاده کنید و یک <button> یا <Link> واقعی به‌عنوان فرزند بدهید؛ tab stop، فعال‌سازی با Enter/Space و حلقهٔ focus از خود آن عنصر می‌آید
• افزودن دستی role="button" و tabIndex به یک <div> کافی نیست — کارت را فقط قابل focus می‌کند ولی فعال‌سازی با Enter/Space را فراهم نمی‌کند (نقض WCAG 2.1.1)
• رنگ‌ها و کنتراست‌ها با استانداردهای WCAG AA سازگار هستند

کامپوننت‌های مرتبط

• MetricCard — اگر نیاز به نمایش یک عدد KPI با sparkline و درصد تغییر دارید، از MetricCard استفاده کنید
• Account — اگر محتوای کارت یک حساب یا پروفایل است، از Account استفاده کنید