جدول (Table)

معرفی

کامپوننت Table برای نمایش داده‌ها در قالب جدول استفاده می‌شود.

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

• برای نمایش داده‌های ساختاریافته با ستون‌های مشخص و بدون نیاز به تعامل پیچیده
• جداول ساده با کمتر از 5 ردیف بدون مرتب‌سازی یا صفحه‌بندی
• نمایش داده‌های مقایسه‌ای ساده

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

• برای داده با sorting، filtering، یا pagination — از DataTable استفاده کنید
• برای نمایش key-value pairs — از dl/dt/dd یا StatDisplay استفاده کنید

زمین بازی

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

استفاده

import { Card, Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from '@partodata/ui'

export default function MyComponent() {
  return (
    <Card>
      <Table>
        <TableCaption>لیست کاربران</TableCaption>
        <TableHeader>
          <TableRow>
            <TableHead>نام</TableHead>
            <TableHead>ایمیل</TableHead>
            <TableHead>نقش</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          <TableRow>
            <TableCell>محمد احمدی</TableCell>
            <TableCell>mohammad@example.com</TableCell>
            <TableCell>ادمین</TableCell>
          </TableRow>
        </TableBody>
      </Table>
    </Card>
  )
}

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

جدول ساده

تراکم

دو تراکم، بدون عدد دستی (نسخهٔ 4.0):

• default برای همهٔ جدول‌های فهرست؛ compact فقط برای جدول‌های پرتراکم منشن که ردیف‌های زیادی باید هم‌زمان دیده شوند.
• متن عادی و عددها وزن regular (400) و اندازهٔ بدنهٔ تراکم جدول را دارند؛ شناسهٔ اصلی ردیف می‌تواند medium (500) باشد. وضعیت و مقدارهای تصمیم‌گیری را caption نکنید و برای هیچ وضعیتی وزن semibold، bold یا black نگذارید. اطلاعات فرعی 12px و regular است؛ نشان بومی اندازه و وزن پیش‌فرض خود (12px / 500) را نگه می‌دارد. جمع‌بندی واقعی در footer می‌تواند medium باشد. سرستون برچسب است: default با 13px / 500 و compact با 12px / 500؛ نقش heading برای آن نگذارید.
• ارتفاع ردیف حداقل است، نه ثابت: سلولی که متنش به خط بعد می‌رود (whitespace-normal) ردیف را بلندتر می‌کند و هیچ‌وقت بریده نمی‌شود.
• سقف محتوای ردیف. فاصلهٔ بالا و پایین سلول 4 پیکسل است، پس ردیف default کنترل‌های sm (30 پیکسل، پیش‌فرض Button) و آواتار تا 32 پیکسل (Avatar size="md") را بدون بلند شدن جا می‌دهد، و ردیف compact کنترل‌های xs (26) و نشان‌ها و آواتار تا 24 پیکسل (Badge، SentimentBadge، Avatar size="sm"). محتوای بزرگ‌تر ردیفش را بلندتر می‌کند و ردیف‌های جدول دیگر یک ارتفاع ندارند. کامپوننت‌های سیستم طراحی وسطِ خط سلول قرار می‌گیرند، نه روی خط کرسی. جای دقیق محتوا 35 پیکسل است (در compact 27): 44 منهای 8 پیکسل فاصله و 1 پیکسل خط زیر ردیف. سلول‌های آمادهٔ DataTable (SentimentCell، FlowCell، …) تراکم جدول را می‌خوانند و زیر این سقف می‌مانند.
• سلولی که Checkbox را مستقیم در خود دارد (ستون انتخاب) فاصلهٔ انتهایی ندارد؛ سلولی که Checkbox را درون فرم یا برچسب دارد (مثل پنل ردیف بازشده) فاصله‌اش را نگه می‌دارد.
• تراکم مال خود جدول است. سلول‌ها تراکم نزدیک‌ترین Table را می‌گیرند: جدولی که داخل سلول جدول دیگری است تراکم خودش را دارد، و هیچ عنصر بالادستی (PageContainer، Card، …) آن را عوض نمی‌کند.
• برای استثنا، className روی TableCell یا TableHead فاصله یا اندازهٔ متن تراکم را جایگزین می‌کند (مثلاً py-10 برای ردیف «داده‌ای نیست»).
• چرا 44: جدول‌های فهرست سوپابیس 40 / حدود 52 با متن 13 Inter است. متن 14 یکان‌بخ از نظر دیداری هم‌اندازهٔ 13 Inter است و خط بلندتری لازم دارد؛ 44 همان ریتم را بدون فاصلهٔ اضافه نگه می‌دارد. (تا 3٫x پیش‌فرض 32 / 31 با متن 12 بود: فشرده‌تر از سوپابیس، برعکسِ خواستهٔ محصول.)
• sm، md و lg از 4.0 منسوخ‌اند: sm ← compact، md و lg ← default (در حالت توسعه یک بار هشدار می‌دهند). ظاهر 3٫x را تکرار نمی‌کنند: sm در 3٫x 32 / 31 / 12 بود، md 40 / 39 / 14 و lg 48 / 51 / 16 (برای lg معادلی در 4.0 نیست).
• جدول‌های پژوهشی با 10 تا 12 ستون ممکن است تراکم سومی (حدود 32 / 32 / 12) لازم داشته باشند. هنوز در سیستم طراحی نیست؛ تا تصمیم آن، از compact استفاده کنید و نیاز را به مسئول سیستم طراحی بگویید.

با Caption

<Table>
  <TableCaption>لیست سفارشات اخیر</TableCaption>
  <TableHeader>...</TableHeader>
  <TableBody>...</TableBody>
</Table>

ردیف‌های تعاملی (interactive)

با interactive روی TableRow، ردیف قابل کلیک و فوکوس‌پذیر با کیبورد می‌شود (Enter/Space فقط وقتی خودِ ردیف فوکوس است، تا دکمه/لینک داخل ردیف رفتار خودش را حفظ کند). برای جدول‌های ساده که کلیک کل ردیف به یک صفحهٔ جزئیات می‌رود مناسب است.

<TableRow interactive onClick={() => router.push(`/campaigns/${row.id}`)}>
  <TableCell>{row.name}</TableCell>
  <TableCell>{row.platform}</TableCell>
</TableRow>

هدر چسبان (stickyHeader)

با stickyHeader، هدر جدول هنگام اسکرول عمودی در بالای کانتینر می‌ماند. چون هدر به نزدیک‌ترین والدِ با overflow غیرقابل‌مشاهده می‌چسبد، خودِ کانتینر (data-slot="table-container") باید ارتفاع محدود داشته باشد؛ اگر containerClassName ندهید، به‌صورت پیش‌فرض max-h-[28rem] overflow-y-auto اعمال می‌شود. برای ارتفاع دلخواه، containerClassName را بدهید:

<Table stickyHeader containerClassName="max-h-[24rem]">
  <TableHeader>...</TableHeader>
  <TableBody>...</TableBody>
</Table>

محو لبه (edgeFade)

با edgeFade روی Table، یک شدو نرم روی لبه‌ای که هنوز محتوای اسکرول‌نشده دارد ظاهر می‌شود (affordance به سبک Supabase). این ویژگی opt-in است (پیش‌فرض false) — تصمیمی تاریخی از نسخه‌ی 2.1.0 تا ارتقا بدون رگرسیون بصری بماند و با مدل اسکرول DataTable تداخل نکند.

<Table edgeFade>
  <TableHeader>...</TableHeader>
  <TableBody>...</TableBody>
</Table>

برای همین محو لبه در جایی خارج از جدول، ScrollArea با fade="inline" را به کار ببرید.

کامپوننت‌ها

Props

Table

TableHeader / TableBody

همه className استاندارد را می‌پذیرند.

TableRow

TableHead

TableCell

TableCaption

TableSortHeader

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

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

• استفاده از المان‌های معنادار HTML (table, thead, tbody, th, td, caption)
• TableHead از scope="col" پشتیبانی می‌کند
• TableCaption برای صفحه‌خوان‌ها عنوان جدول را توصیف می‌کند

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

• DataTable — اگر نیاز به مرتب‌سازی، صفحه‌بندی یا انتخاب ردیف دارید، از DataTable استفاده کنید
• Pagination — برای افزودن صفحه‌بندی سفارشی به جداول ساده استفاده کنید
• StatDisplay — اگر داده شما key-value است و ساختار جدولی ندارد، از StatDisplay استفاده کنید