جدول داده (DataTable)

معرفی

DataTable یک کامپوننت ترکیبی است که جدول، مرتب‌سازی، صفحه‌بندی، انتخاب ردیف، و مدیریت حالت‌های خالی و بارگذاری را در یک API ساده ارائه می‌دهد. این کامپوننت رایج‌ترین الگوی نمایش داده در اپلیکیشن‌های SaaS را پوشش می‌دهد.

جدول سطح مستقلِ روشن‌تر، حاشیهٔ ظریف و گوشه‌های بومی دارد؛ همان محفظهٔ اسکرول این قاب را می‌سازد. آن را داخل Card دیگری نگذارید. رنگِ ردیف‌های عادی و سلول‌های ثابت از سطح خود جدول می‌آید؛ انتخاب و اشاره‌گر حالت‌های خود را حفظ می‌کنند.

متن عادی و عددها از تراکم جدول و وزن regular (400) پیروی می‌کنند؛ شناسهٔ اصلی می‌تواند medium (500) باشد. وضعیت، هویت، اعتماد و دیگر مقدارهای تصمیم‌گیری اندازهٔ بدنه را نگه می‌دارند، نه caption؛ وزن semibold، bold یا black برای وضعیت مجاز نیست. اطلاعات فرعی 12px و regular است؛ نشان بومی نقش پیش‌فرض 12px / 500 خود را حفظ می‌کند. فقط جمع‌بندی واقعی در footer می‌تواند medium باشد. سرستون default همان 13px / 500 و compact همان 12px / 500 است. برای ستون وضعیت از StatusCell استفاده کنید: نقطهٔ معنایی، برچسب متنی با وزن 400 و caption.

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

• لیست داده‌ها با بیش از 5 آیتم که نیاز به مرتب‌سازی یا صفحه‌بندی دارند
• جداول با قابلیت انتخاب برای عملیات دسته‌ای
• جدول هر صفحهٔ فهرست در اپلیکیشن (اینفلوئنسرها، کمپین‌ها، منشن‌ها)، به‌عنوان فرزند قالب ListPage

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

• نمایش ساده 3-5 آیتم بدون تعامل — از Table مستقیم استفاده کنید
• جداول با ساختار بسیار سفارشی — از کامپوننت‌های Table به صورت ترکیبی استفاده کنید
• نمایش کارتی — از Card استفاده کنید

import { DataTable } from '@partodata/ui'

زمین بازی

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

استفاده پایه

import { DataTable, type DataTableColumn } from '@partodata/ui'

interface Influencer {
  id: number
  name: string
  followers: number
  engagementRate: number
}

const columns: DataTableColumn<Influencer>[] = [
  { id: 'name', header: 'نام', cell: (row) => row.name },
  {
    id: 'followers',
    header: 'دنبال‌کننده‌ها',
    cell: (row) => row.followers.toLocaleString('en-US'),
    align: 'end',
  },
  {
    id: 'engagementRate',
    header: 'نرخ تعامل',
    cell: (row) => `${row.engagementRate}٪`,
    align: 'end',
  },
]

const data: Influencer[] = [
  { id: 1, name: 'محمد رضایی', followers: 125000, engagementRate: 4.2 },
  { id: 2, name: 'سارا احمدی', followers: 89000, engagementRate: 6.8 },
  { id: 3, name: 'علی محمدی', followers: 350000, engagementRate: 2.1 },
]

<DataTable columns={columns} data={data} />

با مرتب‌سازی

'use client'

import { useState } from 'react'
import { DataTable, type DataTableColumn, type SortDirection } from '@partodata/ui'

function SortableExample() {
  const [sortColumn, setSortColumn] = useState<string | null>(null)
  const [sortDirection, setSortDirection] = useState<SortDirection | null>(null)

  return (
    <DataTable
      columns={columns}
      data={data}
      sort={{
        column: sortColumn,
        direction: sortDirection,
        onSort: (col, dir) => {
          setSortColumn(col)
          setSortDirection(dir)
        },
      }}
    />
  )
}

با صفحه‌بندی

<DataTable
  columns={columns}
  data={pageData}
  pagination={{
    currentPage: 2,
    totalPages: 10,
    onPageChange: (page) => setCurrentPage(page),
  }}
/>

نوار صفحه‌بندی کامل

با افزودن pageSize/onPageSizeChange و totalRows، نوار پایین علاوه بر شماره‌ی صفحه‌ها، انتخاب تعداد ردیف در هر صفحه، بازه‌ی نتایج و شمار ردیف‌های انتخاب‌شده را هم نشان می‌دهد. هر سه اختیاری‌اند؛ بدون آن‌ها همان نوار شماره‌ایِ وسط‌چین قبلی رندر می‌شود.

<DataTable
  columns={columns}
  data={pageData}
  selection={{ selectedRows, onSelectionChange: setSelectedRows, getRowKey: (row) => row.id }}
  pagination={{
    currentPage,
    totalPages,
    onPageChange: setCurrentPage,
    pageSize,
    onPageSizeChange: setPageSize,
    pageSizeOptions: [10, 20, 50, 100],
    totalRows: 1240,
  }}
/>

با انتخاب ردیف

'use client'

import { useState } from 'react'

function SelectableExample() {
  const [selected, setSelected] = useState<Set<number>>(new Set())

  return (
    <DataTable
      columns={columns}
      data={data}
      selection={{
        selectedRows: selected,
        onSelectionChange: setSelected,
        getRowKey: (row) => row.id,
      }}
    />
  )
}

انتخاب بازه‌ای با Shift-click

بدون هیچ پیکربندی اضافه: یک ردیف را کلیک کنید (لنگر می‌شود)، بعد با Shift ردیف دیگری را کلیک کنید — همه‌ی ردیف‌های بینشان همان حالتِ جدیدِ ردیفِ کلیک‌شده را می‌گیرند. لنگر تا کلیکِ ساده‌ی بعدی ثابت می‌ماند، پس چند Shift-click پشتِ سرِ هم همه از یک نقطه بازه می‌سازند. ردیف‌های غیرقابل‌انتخاب (isRowSelectable که false برگرداند) از بازه کنار گذاشته می‌شوند — دقیقاً مثل رفتارشان در «انتخاب همه».

تراکم

مثل Table: default (سرِ جدول 40، ردیف حداقل 44، متن 14) برای همهٔ جدول‌های فهرست، و size="compact" (36 / 36 / 13) برای جدول‌های پرتراکم منشن. دلیل عددها در صفحهٔ Table آمده است. درون یک ListPage، size نمی‌دهید: قالب تراکم همهٔ صفحه‌های فهرست را یکی می‌کند.

• محتوای ستون‌ها را زیر سقف تراکم نگه دارید تا همهٔ ردیف‌ها یک ارتفاع داشته باشند. در default کنترل‌های sm (30 پیکسل، پیش‌فرض Button) و آواتار تا 32 پیکسل (Avatar size="md") جا می‌شوند، و در compact کنترل‌های xs (26) و نشان‌ها و آواتار تا 24 پیکسل (Avatar size="sm").
• تراکم مال خود جدول است. DataTable فشرده داخل PageContainer فشرده می‌ماند، و جدولی که در ردیف بازشدهٔ (expansion) آن قرار می‌گیرد تراکم خودش را دارد.
• با virtualize، مقدار rowHeight را برابر ارتفاع ردیف بدهید: 44 در default و 36 در compact (ردیف‌های 3٫x حدود 31 پیکسل بودند). فاصله‌گذاری و اسکرول از همین عدد حساب می‌شود.
• اسکلت بارگذاری بیرون از جدول (TableSkeleton) هم size="compact" می‌گیرد، تا جایگزین شدنش با جدول پرش نداشته باشد.

حالت‌های بارگذاری، خطا و خالی

جدول حالت‌هایش را خودش نمی‌کشد: قالب صفحه آن‌ها را جای کل جدول می‌گذارد. در صفحهٔ فهرست با state قالب ListPage، و برای جدولی که جدا از صفحه بارگذاری می‌شود (بخشی از صفحهٔ جزئیات) با state همان DetailSection یا یک PageState:

import { DataTable, useAsync } from '@partodata/ui'
import { ListPage, pageState } from '@partodata/ui/templates'

const { data, isLoading, error, run } = useAsync<Paged<Influencer>>()

;<ListPage
  title="اینفلوئنسرها"
  state={pageState({
    data: data?.items,
    isLoading,
    error,
    onRetry: load,
    emptyCopy: { title: 'هنوز اینفلوئنسری ثبت نشده است' },
  })}
>
  <DataTable columns={columns} data={data?.items ?? []} />
</ListPage>

• بارگذاری اول: اسکلتی به شکل جدول جای جدول؛ هنگام بارگذاری صفحهٔ بعد، جست‌وجو یا فیلتر ردیف‌ها کم‌رنگ سر جایشان می‌مانند.
• خطا: ErrorState با «تلاش مجدد» (که onRetry را صدا می‌زند) جای جدول.
• خالی: وقتی جست‌وجو یا فیلتری فعال است «نتیجه‌ای یافت نشد» با «پاک کردن فیلترها»؛ وگرنه عنوان emptyCopy که نام آنچه نیست را می‌برد. سرستون‌های جدول نمی‌مانند.

propهای isLoading، loadingRows و emptyState خود جدول فقط برای سازگاری با کدهای پیشین مانده‌اند؛ در صفحه آن‌ها را به کار نبرید.

ترکیب کامل

'use client'

import { useState } from 'react'
import { DataTable, type DataTableColumn, type SortDirection, Avatar, Badge, formatNumber } from '@partodata/ui'
import { PlatformMark } from '@partodata/ui/social'

function FullExample() {
  const [page, setPage] = useState(1)
  const [sortCol, setSortCol] = useState<string | null>(null)
  const [sortDir, setSortDir] = useState<SortDirection | null>(null)
  const [selected, setSelected] = useState<Set<number>>(new Set())

  const columns: DataTableColumn<Influencer>[] = [
    {
      id: 'name',
      header: 'نام',
      sortable: true,
      cell: (row) => (
        <div className="flex items-center gap-2">
          <Avatar src={row.avatar} fallback={row.name[0]} size="sm" />
          <span className="font-medium">{row.name}</span>
        </div>
      ),
    },
    {
      id: 'platform',
      header: 'پلتفرم',
      cell: (row) => <PlatformMark source={row.platform} variant="badge" showLabel />,
    },
    {
      id: 'followers',
      header: 'دنبال‌کننده‌ها',
      sortable: true,
      align: 'end',
      cell: (row) => formatNumber(row.followers),
    },
    {
      id: 'status',
      header: 'وضعیت',
      cell: (row) => <Badge variant={row.active ? 'success' : 'default'}>{row.active ? 'فعال' : 'غیرفعال'}</Badge>,
    },
  ]

  return (
    <DataTable
      columns={columns}
      data={influencers}
      size="compact"
      striped
      sort={{
        column: sortCol,
        direction: sortDir,
        onSort: (col, dir) => {
          setSortCol(col)
          setSortDir(dir)
        },
      }}
      selection={{
        selectedRows: selected,
        onSelectionChange: setSelected,
        getRowKey: (row) => row.id,
      }}
      pagination={{
        currentPage: page,
        totalPages: 12,
        onPageChange: setPage,
      }}
      resultCount="142 اینفلوئنسر"
    />
  )
}

کلیک روی ردیف

با onRowClick، ردیف‌های بدنه تعاملی می‌شوند: فوکوس‌پذیر با کیبورد (Tab) و قابل فعال‌سازی با Enter/Space، و کلیک/فعال‌سازی این callback را با (row, rowIndex) صدا می‌زند. برای «کلیک ردیف → صفحهٔ جزئیات» مناسب است. کنترل‌های تعاملی داخل سلول (دکمه، منو) رفتار خودشان را حفظ می‌کنند.

<DataTable columns={columns} data={campaigns} onRowClick={(row) => router.push(`/campaigns/${row.id}`)} />

فیلتر facetedِ ستون‌محور

DataTableFacetedFilter یک چندانتخابیِ Popover + Command است برای enumهای محدودِ دامنه — پلتفرم، احساس، موضع، وضعیت، شدت، رده‌ی تعامل. کنارِ هر گزینه، شمارِ نتایج نمایش داده می‌شود.

'use client'
import { DataTable, DataTableFacetedFilter } from '@partodata/ui'

type Platform = 'instagram' | 'telegram' | 'x'
const PLATFORMS: { value: Platform; label: string }[] = [
  { value: 'instagram', label: 'اینستاگرام' },
  { value: 'telegram', label: 'تلگرام' },
  { value: 'x', label: 'ایکس' },
]

const [platforms, setPlatforms] = useState<Platform[]>([])

<DataTableFacetedFilter
  title="پلتفرم"
  options={PLATFORMS}
  selected={platforms}
  onSelectedChange={setPlatforms}
  facets={{ instagram: 1240, telegram: 87, x: 12 }}
/>

فیلتر با نوع مقدار گزینه‌هایش تایپ می‌شود: وقتی گزینه‌ها و وضعیت با union برنامه تایپ شوند (useState<Platform[]>)، selected و onSelectedChange هم Platform[] هستند و انتخاب بی‌تبدیل نوع (بدون as Platform[]) به APIای می‌رسد که با همان union تایپ شده است. گزینه‌ای بیرون از union خطای نوع است. با مقدارهای string مثل قبل کار می‌کند. در صفحهٔ فهرست، هر تغییر فیلتر صفحه را هم به 1 برمی‌گرداند (filterBy در ListPage).

جدول در صفحهٔ فهرست (جست‌وجو + فیلترها + خروجی)

در صفحهٔ فهرست، جدول فرزند قالب ListPage است و جست‌وجو، فیلترها و اقدام‌های بالای آن propهای همان قالب‌اند: قالب نوارابزار را می‌سازد، همهٔ کنترل‌ها را هم‌قد می‌کند، به هر کدام عرض محتوایش را می‌دهد، جست‌وجو را با عرض نام‌دار می‌گذارد و فاصلهٔ 16 پیکسلی تا جدول را خودش تعیین می‌کند. پس این ردیف را با PageToolbar، FilterBar یا div و flex نسازید و به کنترل‌های داخلش size یا کلاس عرض ندهید. جدول خودش size، pagination، emptyState و isLoading ندارد.

نمونهٔ کامل و کامپایل‌شده در ListPage آمده است.

جدول ویژگی‌ها

DataTable

DataTableColumn

DataTablePagination

DataTableFacetedFilter

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

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

• ستون‌های قابل مرتب‌سازی از aria-sort استفاده می‌کنند
• همه نام‌های قابل‌دسترس از prop به نام locale پیروی می‌کنند (fa پیش‌فرض، ar، en) — چک‌باکس انتخاب، دکمه باز/بستن ردیف و دستگیره تغییر اندازه ستون
• نشان اولویت مرتب‌سازی چندستونه معنای خود را با یک متن sr-only اعلام می‌کند (روی یک <span> بدون role، aria-label نام نمی‌سازد)
• حالت بارگذاری از اسکلتون بصری استفاده می‌کند
• ساختار جدول از تگ‌های معنایی HTML (table, thead, tbody, th, td) پیروی می‌کند

v2 features (نمایان‌سازی ستون، expansion، pinning، export)

'use client'
import {
  DataTable,
  DataTableColumnVisibilityToggle,
  DataTableExportButton,
} from '@partodata/ui'

const [visibility, setVisibility] = useState({})
const [expandedRows, setExpandedRows] = useState(new Set<number>())

<div className="flex items-center justify-end gap-2">
  <DataTableColumnVisibilityToggle
    columns={columns}
    visibility={{ visible: visibility, onVisibilityChange: setVisibility }}
  />
  <DataTableExportButton columns={columns} data={rows} filename="pages.csv" />
</div>

<DataTable
  columns={[
    { id: 'name', header: 'نام', cell: (r) => r.name, pinned: 'start', width: 200 },
    { id: 'engagement', header: 'تعامل', cell: (r) => r.engagement },
    { id: 'notes', header: 'یادداشت', cell: (r) => r.notes, defaultVisible: false },
  ]}
  data={rows}
  columnVisibility={{ visible: visibility, onVisibilityChange: setVisibility }}
  expansion={{
    expandedRows,
    onExpandedRowsChange: setExpandedRows,
    renderExpandedRow: (r) => <div className="p-4 text-sm">{r.detailsHtml}</div>,
  }}
/>

• columnVisibility (4.2) — show/hide columns via a checkbox dropdown. defaultVisible: false on a column hides it until toggled on.
• expansion (4.5) — adds a chevron column; clicking expands a full-width detail row below.
• pinned: 'start' | 'end' (4.6) — sticky columns که در زمان horizontal scroll قابل دیدن می‌مانند. RTL-aware via CSS logical inset.
• width: number — عرض ثابت پیکسل برای layout header (همراه با pinning مفید است).
• <DataTableExportButton> (4.9) — dropdown با CSV download + TSV-clipboard. exportValue در ستون برای cellهای React-node serialize را override می‌کند.

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

• ListPage — قالب صفحهٔ فهرست: جست‌وجو، فیلترها، اقدام‌ها، حالت‌ها و صفحه‌بندی جدول؛ جدول فرزند آن است
• Table — اگر داده‌های شما ساده هستند و نیاز به مرتب‌سازی یا صفحه‌بندی ندارند، از Table استفاده کنید
• Card — اگر نمایش کارتی مناسب‌تر از جدول است، از Card در grid layout استفاده کنید
• DataTableCells — renderer های مخصوص cell جدول (sparkline، trend، status، …)