جدول (Table)

کامپوننت جدول واکنش‌گرا با پشتیبانی کامل از RTL و حالت تاریک

نصب (Installation)

1npx @quark-lab/rad-ui add table

نمونه‌ها (Examples)

استفاده پایه (Basic Usage)

ساده‌ترین حالت استفاده از جدول با سرستون، ردیف‌ها و توضیحات.

لیست فاکتورهای اخیر شما.
فاکتوروضعیتروش پرداختمبلغ
INV001پرداخت شدهکارت اعتباری۲۵۰,۰۰۰ تومان
INV002در انتظاردرگاه پرداخت۱۵۰,۰۰۰ تومان
INV003پرداخت نشدهانتقال بانکی۳۵۰,۰۰۰ تومان
INV004پرداخت شدهکارت اعتباری۴۵۰,۰۰۰ تومان
INV005پرداخت شدهدرگاه پرداخت۵۵۰,۰۰۰ تومان
مشاهده کد
1import {
2  Table,
3  TableBody,
4  TableCaption,
5  TableCell,
6  TableHead,
7  TableHeader,
8  TableRow,
9} from "@/components/ui/table";
10
11const invoices = [
12  {
13    invoice: "INV001",
14    paymentStatus: "پرداخت شده",
15    totalAmount: "۲۵۰,۰۰۰ تومان",
16    paymentMethod: "کارت اعتباری",
17  },
18  // ...
19];
20
21export default function BasicExample() {
22  return (
23    <Table>
24      <TableCaption>لیست فاکتورهای اخیر شما.</TableCaption>
25      <TableHeader>
26        <TableRow>
27          <TableHead className="w-[100px]">فاکتور</TableHead>
28          <TableHead>وضعیت</TableHead>
29          <TableHead>روش پرداخت</TableHead>
30          <TableHead className="text-end">مبلغ</TableHead>
31        </TableRow>
32      </TableHeader>
33      <TableBody>
34        {invoices.map((invoice) => (
35          <TableRow key={invoice.invoice}>
36            <TableCell className="font-medium">{invoice.invoice}</TableCell>
37            <TableCell>{invoice.paymentStatus}</TableCell>
38            <TableCell>{invoice.paymentMethod}</TableCell>
39            <TableCell className="text-end">{invoice.totalAmount}</TableCell>
40          </TableRow>
41        ))}
42      </TableBody>
43    </Table>
44  );
45}

با پاورقی (With Footer)

استفاده از TableFooter برای نمایش مجموع یا خلاصه داده‌ها.

لیست فاکتورهای اخیر شما.
فاکتوروضعیتروش پرداختمبلغ
INV001پرداخت شدهکارت اعتباری۲۵۰,۰۰۰ تومان
INV002در انتظاردرگاه پرداخت۱۵۰,۰۰۰ تومان
INV003پرداخت نشدهانتقال بانکی۳۵۰,۰۰۰ تومان
مجموع۷۵۰,۰۰۰ تومان
مشاهده کد
1import {
2  Table,
3  TableBody,
4  TableCaption,
5  TableCell,
6  TableFooter,
7  TableHead,
8  TableHeader,
9  TableRow,
10} from "@/components/ui/table";
11
12const invoices = [
13  {
14    invoice: "INV001",
15    paymentStatus: "پرداخت شده",
16    totalAmount: "۲۵۰,۰۰۰ تومان",
17    paymentMethod: "کارت اعتباری",
18  },
19  // ...
20];
21
22export default function FooterExample() {
23  return (
24    <Table>
25      <TableCaption>لیست فاکتورهای اخیر شما.</TableCaption>
26      <TableHeader>
27        <TableRow>
28          <TableHead className="w-[100px]">فاکتور</TableHead>
29          <TableHead>وضعیت</TableHead>
30          <TableHead>روش پرداخت</TableHead>
31          <TableHead className="text-end">مبلغ</TableHead>
32        </TableRow>
33      </TableHeader>
34      <TableBody>
35        {invoices.map((invoice) => (
36          <TableRow key={invoice.invoice}>
37            <TableCell className="font-medium">{invoice.invoice}</TableCell>
38            <TableCell>{invoice.paymentStatus}</TableCell>
39            <TableCell>{invoice.paymentMethod}</TableCell>
40            <TableCell className="text-end">{invoice.totalAmount}</TableCell>
41          </TableRow>
42        ))}
43      </TableBody>
44      <TableFooter>
45        <TableRow>
46          <TableCell colSpan={3}>مجموع</TableCell>
47          <TableCell className="text-end">۷۵۰,۰۰۰ تومان</TableCell>
48        </TableRow>
49      </TableFooter>
50    </Table>
51  );
52}

مرجع API (API Reference)

Table

پراپ‌های کامپوننت اصلی جدول. جدول در یک container با اسکرول افقی قرار می‌گیرد.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی برای جدول
childrenReact.ReactNode-محتوای جدول شامل TableHeader، TableBody، TableFooter و TableCaption

TableHead

پراپ‌های سرستون جدول.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی برای سرستون
colSpannumber-تعداد ستون‌هایی که سرستون باید پوشش دهد

TableCell

پراپ‌های سلول جدول.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی برای سلول
colSpannumber-تعداد ستون‌هایی که سلول باید پوشش دهد

دسترسی‌پذیری (Accessibility)

ساختار معنایی (Semantic Structure)

از المان‌های معنایی HTML مانند <table>، <thead>، <tbody> و <caption> استفاده می‌شود که به خوانندگان صفحه کمک می‌کند ساختار جدول را درک کنند.

ناوبری کیبورد (Keyboard Navigation)

  • Tab - حرکت بین عناصر قابل فوکوس در جدول
  • Arrow Keys - ناوبری بین سلول‌ها (در صورت استفاده از Data Table)

توضیحات جدول (Table Caption)

از TableCaption برای توصیف محتوای جدول استفاده کنید تا کاربران خواننده صفحه بتوانند هدف جدول را درک کنند.

بهترین شیوه‌ها (Best Practices)

استفاده از TableCaption (Use TableCaption)

همیشه از TableCaption برای توصیف محتوای جدول استفاده کنید. این کار به دسترسی‌پذیری کمک می‌کند.

تراز متن در RTL (Text Alignment in RTL)

برای تراز متن از کلاس‌های منطقی مانند text-start و text-end استفاده کنید تا جدول در هر دو جهت RTL و LTR به درستی نمایش داده شود.

جدول‌های واکنش‌گرا (Responsive Tables)

کامپوننت Table به صورت پیش‌فرض در یک container با اسکرول افقی قرار دارد. برای جدول‌های بزرگ، داده‌ها به صورت خودکار قابل اسکرول خواهند بود.

پاورقی جدول (Table Footer)

از TableFooter برای نمایش مجموع، میانگین یا سایر خلاصه‌های داده‌ها استفاده کنید.

نحوه استفاده (Usage)

1import {
2  Table,
3  TableBody,
4  TableCaption,
5  TableCell,
6  TableFooter,
7  TableHead,
8  TableHeader,
9  TableRow,
10} from "@/components/ui/table";
11
12export default function TableExample() {
13  return (
14    <Table>
15      <TableCaption>توضیحات جدول</TableCaption>
16      <TableHeader>
17        <TableRow>
18          <TableHead>عنوان</TableHead>
19          <TableHead>وضعیت</TableHead>
20          <TableHead className="text-end">مبلغ</TableHead>
21        </TableRow>
22      </TableHeader>
23      <TableBody>
24        <TableRow>
25          <TableCell className="font-medium">آیتم ۱</TableCell>
26          <TableCell>فعال</TableCell>
27          <TableCell className="text-end">۱۰۰,۰۰۰ تومان</TableCell>
28        </TableRow>
29      </TableBody>
30      <TableFooter>
31        <TableRow>
32          <TableCell colSpan={2}>مجموع</TableCell>
33          <TableCell className="text-end">۱۰۰,۰۰۰ تومان</TableCell>
34        </TableRow>
35      </TableFooter>
36    </Table>
37  );
38}

مثال‌های پیشرفته (Advanced Examples)

جدول با استایل سفارشی (Custom Styled Table)

می‌توانید با className ظاهر جدول و سلول‌ها را تغییر دهید.

عنوانمقدار
آیتم ۱۱۰۰
مشاهده کد
1<Table>
2  <TableHeader>
3    <TableRow>
4      <TableHead className="bg-primary/10">عنوان</TableHead>
5      <TableHead className="bg-primary/10">مقدار</TableHead>
6    </TableRow>
7  </TableHeader>
8  <TableBody>
9    <TableRow className="bg-muted/30">
10      <TableCell>آیتم ۱</TableCell>
11      <TableCell>۱۰۰</TableCell>
12    </TableRow>
13  </TableBody>
14</Table>

جدول بدون حاشیه (Borderless Table)

حذف حاشیه ردیف‌ها با className سفارشی.

نامنقش
علیتوسعه‌دهنده
ساراطراح
مشاهده کد
1<Table>
2  <TableHeader>
3    <TableRow className="border-0 hover:bg-transparent">
4      <TableHead>نام</TableHead>
5      <TableHead>نقش</TableHead>
6    </TableRow>
7  </TableHeader>
8  <TableBody>
9    <TableRow className="border-0">
10      <TableCell>علی</TableCell>
11      <TableCell>توسعه‌دهنده</TableCell>
12    </TableRow>
13    <TableRow className="border-0">
14      <TableCell>سارا</TableCell>
15      <TableCell>طراح</TableCell>
16    </TableRow>
17  </TableBody>
18</Table>