Bileşenler

DataTable

Sıralama, seçim, sütun görünürlüğü ve sanallaştırma ile büyük ve değişen verileri tabloda gösterir.

Storybook: Storybook
Kaynak kod: Kaynak kod

Kurulum

Paket: @bigbang/ui
İçe aktarma: import { DataTable } from '@bigbang/ui';
Kaynak: DataTable.tsx
Storybook: DataTable · Playground

DataTable, @bigbang/ui paketindedir ve TanStack Table (v9) ile TanStack Virtual üzerine kuruludur; ikisi de pakete bağımlılık olarak gelir. Kurulum ve stil dosyaları Button ile aynıdır; ayrıntılar için Button kod sekmesine bakın.

import { createDataTableColumnHelper, DataTable } from '@bigbang/ui';

type Row = { id: string; name: string; count: number };

const helper = createDataTableColumnHelper<Row>();

// Sütunları bileşenin dışında tanımlayın ya da useMemo ile kararlı tutun.
const columns = [
  helper.accessor('name', { header: 'Ad', meta: { rowHeader: true } }),
  helper.accessor('count', { header: 'Adet', meta: { numeric: true } }),
];

<DataTable columns={columns} data={rows} getRowId={(row) => row.id} caption="Öğe listesi" />;

Özellikler

columnsZorunlu

Açıklama: Sütun tanımları (TanStack ColumnDef). Diziyi kararlı tutun (useMemo ya da modül sabiti). Hücre seçenekleri meta içinde verilir: align, numeric, truncate, headerLabel, rowHeader.
Tür: DataTableColumnDef<TRow>[]

dataZorunlu

Açıklama: Gösterilecek satırlar. Diziyi çizimler arasında kararlı tutun; her çizimde yeni dizi vermek tabloyu yeniden hesaplatır.
Tür: TRow[]

getRowIdZorunlu

Açıklama: Satır için kararlı ve benzersiz bir kimlik döndürür, örneğin kayıt kimliği. Seçim ve odak bu kimliği izler; değişen verilerde sırayı kimlik olarak kullanmayın.
Tür: (row: TRow, index: number) => string

captionZorunlu

Açıklama: Tablonun başlığı. Tabloyu ve kaydırma bölgesini ekran okuyucuya adlandırır.
Tür: ReactNode

captionHidden

Açıklama: Başlığı görsel olarak gizler, yardımcı teknolojiler için korur.
Tür: boolean
Varsayılan: false

sorting

Açıklama: Sıralama durumu, [{ id: 'name', desc: false }]. Verilirse sıralama kontrollü olur; onSortingChange ile birlikte kullanın.
Tür: SortingState

defaultSorting

Açıklama: Sıralamayı kontrol etmediğinizde ilk sıralama.
Tür: SortingState

onSortingChange

Açıklama: Kullanıcı sıralanabilir bir başlığa tıkladığında yeni sıralamayla çağrılır.
Tür: (sorting: SortingState) => void

manualSorting

Açıklama: Sıralama sunucuda yapılır: tablo data'yı verilen sırayla gösterir ve sıralamayı yalnızca onSortingChange ile bildirir.
Tür: boolean
Varsayılan: false

selectionMode

Açıklama: Bir onay kutusu sütunu ekler. multiple ayrıca karışık durumu gösteren tümünü seç kutusu ekler; single aynı anda tek satıra izin verir.
Tür: 'none' | 'single' | 'multiple'
Varsayılan: 'none'

rowSelection

Açıklama: Seçili satırlar, { [satırKimliği]: true }. Verilirse seçim kontrollü olur; onRowSelectionChange ile birlikte kullanın.
Tür: RowSelectionState

defaultRowSelection

Açıklama: Seçimi kontrol etmediğinizde ilk seçim.
Tür: RowSelectionState

onRowSelectionChange

Açıklama: Kullanıcı bir satırı ya da tümünü seç kutusunu değiştirdiğinde yeni seçimle çağrılır.
Tür: (selection: RowSelectionState) => void

getRowLabel

Açıklama: Satırı adlandıran metni döndürür, örneğin adı. Satır onay kutusunu etiketler ("Öğe 1 satırını seç"). Verilmezse satır kimliği kullanılır.
Tür: (row: TRow) => string

columnVisibility

Açıklama: Sütun görünürlüğü; { [sütunKimliği]: false } sütunu gizler. Verilirse görünürlük kontrollü olur.
Tür: ColumnVisibilityState

defaultColumnVisibility

Açıklama: Görünürlüğü kontrol etmediğinizde ilk görünürlük.
Tür: ColumnVisibilityState

onColumnVisibilityChange

Açıklama: Bir sütun gösterildiğinde ya da gizlendiğinde yeni görünürlükle çağrılır.
Tür: (visibility: ColumnVisibilityState) => void

columnToggle

Açıklama: Tablonun üstüne yerleşik sütun butonunu ekler; her sütun için bir onay kutusu içeren bir panel açar.
Tür: boolean
Varsayılan: false

density

Açıklama: En az satır yüksekliği: compact 32 px, standard 40 px, comfortable 48 px. Başlık satırı standard yoğunlukta 40 px'tir.
Tür: 'compact' | 'standard' | 'comfortable'
Varsayılan: 'standard'

stickyHeader

Açıklama: Gövde kayarken üst bilgi hücrelerini yukarıda tutar. Kaydırma kapsayıcısına scrollClassName ile bir yükseklik verin.
Tür: boolean
Varsayılan: false

hoverable

Açıklama: Gövde satırını üzerine gelince yalnızca renk değişimiyle boyar.
Tür: boolean
Varsayılan: true

striped

Açıklama: Her ikinci gövde satırını boyar.
Tür: boolean
Varsayılan: false

status

Açıklama: Tablonun gösterdiği durum: ready satırlar; loading üst bilginin altında iskelet satırlar ve aria-busy; empty ve filtered-empty bir ileti; error yeniden deneme butonlu bir ileti. Satırı olmayan ready tablo boş iletisini gösterir.
Tür: 'ready' | 'loading' | 'empty' | 'filtered-empty' | 'error'
Varsayılan: 'ready'

onClearFilters

Açıklama: filtered-empty iletisine "Filtreleri temizle" butonu ekler.
Tür: () => void

onRetry

Açıklama: error iletisine "Yeniden dene" butonu ekler.
Tür: () => void

rowActions

Açıklama: Satırın işlemlerini, örneğin IconButton'ları, satır sonunda yapışık son sütunda gösterir. Her işlem ayrı bir sekme durağıdır ve adı olmalıdır.
Tür: (row: TRow) => ReactNode

onRowOpen

Açıklama: İlk sütunun hücre içeriğini, satırla çağrılan bir butona çevirir; böylece satır yalnızca tıklanır olmaz.
Tür: (row: TRow) => void

renderExpanded

Açıklama: Verildiğinde her satırın başına bir aç/kapat düğmesi eklenir; açılan satırın altındaki ayrıntı içeriğini döndürür.
Tür: (row: TRow) => ReactNode

getRowCanExpand

Açıklama: Bir satırın açılıp açılamayacağını belirler. Varsayılan: her satır açılabilir.
Tür: (row: TRow) => boolean

expanded

Açıklama: Açık satırlar, satır kimliğine göre (kontrollü).
Tür: Record<string, boolean>

defaultExpanded

Açıklama: Başlangıçta açık satırlar (kontrolsüz).
Tür: Record<string, boolean>

onExpandedChange

Açıklama: Açık satırlar değiştiğinde yeni durumla çağrılır.
Tür: (expanded: Record<string, boolean>) => void

virtualize

Açıklama: Yalnızca görünen satırları ve bir payı üretir; dolgu satırları kaydırma yüksekliğini korur. Yaklaşık 1.000 satırdan itibaren kullanın. Sabit yükseklikli bir kaydırma kapsayıcısı (scrollClassName) ve eşit yükseklikte satırlar ister.
Tür: boolean | { estimateRowHeight?: number; overscan?: number; }
Varsayılan: false

totalRowCount

Açıklama: data verinin yalnızca bir kısmını, örneğin sunucudan gelen bir sayfayı, taşıyorsa toplam satır sayısı. aria-rowcount değerini belirler.
Tür: number

messages

Açıklama: Kitaplık metinlerini değiştirir, örneğin { empty: 'Henüz öğe yok' }. {column}, {row} ve {count} yer tutucuları ilgili metinlerde değiştirilir.
Tür: Partial<Record<DataTableMessageKey, string>>

scrollClassName

Açıklama: Tabloyu tutan kaydırma kapsayıcısının sınıfları, örneğin sabit üst bilgi ya da sanallaştırılmış liste için max-h-96.
Tür: string

className

Açıklama: Yalnızca yerleşim için: tüm bileşenin genişliği ve kenar boşlukları.
Tür: string

Sütun tanımları

columns, TanStack Table v9 sütun tanımlarıdır. createDataTableColumnHelper<Row>() türleri sizin yerinize bağlar. Sütun meta alanı şu seçenekleri alır:

`meta`	Anlam
`align`	`start`, `center` ya da `end` hizalama.
`numeric`	Sona hizalar ve tabular rakamlar kullanır.
`truncate`	Uzun metni tek satırda keser; sütunun genişliği olmalıdır.
`headerLabel`	Başlık metin değilse sıralama butonunun, sütun panelinin ve duyuruların adı.
`rowHeader`	Sütunun hücrelerini satır başlığı (`<th scope="row">`) yapar.

const columns = [
  helper.accessor('name', { header: 'Ad', meta: { rowHeader: true } }),
  // Özel hücre: durum sözlüğünden bir StatusBadge
  helper.accessor('status', {
    header: 'Durum',
    enableSorting: false,
    cell: (context) => <StatusBadge status={context.getValue()} />,
  }),
  // Başlık metin değil: headerLabel ile ad verin
  helper.accessor('owner', { header: () => <Icon name="user" />, meta: { headerLabel: 'Sahibi' } }),
];

enableSorting: false sütunu sıralanamaz yapar; enableHiding: false sütun panelinden çıkarır; sortFn ve diğer TanStack seçenekleri geçerlidir.

Parçalar

Parça	Öğe	Özellikler
`DataTable.ColumnToggle`	`<div>` ve buton	`columns` (`{ id, label, visible }`), `onVisibleChange`, `label`. `columnToggle` özelliğinin kullandığı parça; özel bir araç çubuğunda tek başına da kullanılabilir.

Dışa aktarılanlar

DataTable, createDataTableColumnHelper, dataTableStyles ve şu türler: DataTableProps, DataTableColumnDef, DataTableColumnMeta, DataTableMessages, DataTableColumnVisibility, DataTableRowSelection, DataTableSorting.

Veri öznitelikleri

data-component="data-table", data-status: dış kapsayıcıda.
data-part: toolbar, column-toggle, column-toggle-panel, select-header, select-cell, sort, open, actions-header, actions-cell, skeleton-row, state-row, message, spacer, footer, live.
Tablo ve satır öznitelikleri Table’dan gelir (data-density, data-selected vb.).
data-pin (start, end) ve sabit alanın kenarındaki hücrede data-pin-edge: sabit sütun hücrelerinde. data-part: expand-header, expand-cell, expanded-row.

Durumu yönetme

const [sorting, setSorting] = useState<DataTableSorting>([{ id: 'count', desc: true }]);
const [selection, setSelection] = useState<DataTableRowSelection>({});

<DataTable
  columns={columns}
  data={rows}
  getRowId={(row) => row.id}
  caption="Öğe listesi"
  sorting={sorting}
  onSortingChange={setSorting}
  selectionMode="multiple"
  rowSelection={selection}
  onRowSelectionChange={setSelection}
/>;

Sunucu tarafı sıralama ve sayfalama

<DataTable
  columns={columns}
  data={page.rows}
  getRowId={(row) => row.id}
  caption="Öğe listesi"
  manualSorting
  sorting={sorting}
  onSortingChange={setSorting}
  totalRowCount={page.total}
  status={isLoading ? 'loading' : isError ? 'error' : 'ready'}
  onRetry={refetch}
  footer={<Pagination … />}
/>

Sanallaştırma

<DataTable columns={columns} data={rows} getRowId={(row) => row.id} caption="Öğe listesi" virtualize scrollClassName="max-h-96" density="compact" />

virtualize={{ estimateRowHeight: 40, overscan: 12 }} satır yüksekliğini ve payı ayarlar. Varsayılan satır yüksekliği compact için 32 px, standard için 40 px, comfortable için 48 px’tir.

Metinleri değiştirme

<DataTable … status="empty" messages={{ empty: 'Henüz öğe yok' }} />

messages anahtarları: empty, filtered-empty, clear-filters, error, retry, loading, select-all, select-row, select-column, actions, columns, sorted-asc, sorted-desc, sorted-none, selected-count. {column}, {row} ve {count} yer tutucuları ilgili metinlerde değiştirilir.