DataTable

数据表格：列定义驱动，内置排序、全局搜索、分页与行选择，并支持加载骨架与空状态；排序、分页、选择均可受控或非受控。

安装

添加组件

pnpm dlx @elyri/cli@latest add data-table

示例

基础用法

传入 columns 与 data 即可，accessor 决定取值列，cell 可自定义单元格。

Workspace members
	Role	Status
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Grace Hopper	admin	Paused	5
Linus Torvalds	viewer	Invited	1
Margaret Hamilton	editor	Active	4
Katherine Johnson	viewer	Invited	2

import { DataTable } from './components/elyri/DataTable';
import type { DataTableColumn } from './components/elyri/DataTable';

interface Member {
  id: number;
  name: string;
  role: string;
  status: string;
  seats: number;
}

const members = [
  { id: 1, name: 'Ada Lovelace', role: 'admin', status: 'active', seats: 3 },
  { id: 2, name: 'Alan Turing', role: 'editor', status: 'active', seats: 2 },
  { id: 3, name: 'Grace Hopper', role: 'admin', status: 'paused', seats: 5 },
];

const columns: DataTableColumn<Member>[] = [
  { id: 'name', header: 'Member', accessor: 'name', sortable: true },
  { id: 'role', header: 'Role', accessor: 'role' },
  { id: 'status', header: 'Status', accessor: 'status', align: 'center' },
  { id: 'seats', header: 'Seats', accessor: 'seats', sortable: true, align: 'right' },
];

export function Example() {
  return <DataTable caption="Workspace members" columns={columns} data={members} />;
}

排序

列开启 sortable 后点击表头在升序 / 降序 / 取消间循环，aria-sort 同步更新。

	Role	Status
Grace Hopper	admin	Paused	5
Margaret Hamilton	editor	Active	4
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Katherine Johnson	viewer	Invited	2
Linus Torvalds	viewer	Invited	1

import { DataTable } from './components/elyri/DataTable';

export function Example() {
  return (
    <DataTable
      columns={columns}
      data={members}
      defaultSort={{ columnId: 'seats', direction: 'desc' }}
    />
  );
}

全局搜索

开启 searchable 显示搜索框，对所有可搜索列做忽略大小写的包含匹配。

	Role	Status
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Grace Hopper	admin	Paused	5
Linus Torvalds	viewer	Invited	1
Margaret Hamilton	editor	Active	4
Katherine Johnson	viewer	Invited	2

import { DataTable } from './components/elyri/DataTable';

export function Example() {
  return <DataTable searchable title="Members" columns={columns} data={members} />;
}

行选择

开启 selectable 出现选择列，表头支持全选当前页与半选态，底部展示已选摘要。

	Role	Status
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Grace Hopper	admin	Paused	5

import { DataTable } from './components/elyri/DataTable';

export function Example() {
  return (
    <DataTable
      selectable
      columns={columns}
      data={members}
      defaultSelectedKeys={['1']}
      pageSizeOptions={[3, 6]}
      defaultPageSize={3}
    />
  );
}

分页

通过 pageSize 与 pageSizeOptions 启用分页，支持受控与非受控。

	Role	Status
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Grace Hopper	admin	Paused	5

import { DataTable } from './components/elyri/DataTable';

export function Example() {
  return (
    <DataTable columns={columns} data={members} pageSize={3} pageSizeOptions={[3, 6]} />
  );
}

加载与空状态

loading 渲染骨架行，数据为空时展示内置空状态，也可用 empty 自定义。

	Role	Status

	Role	Status
暂无数据

import { DataTable } from './components/elyri/DataTable';

export function Example() {
  return (
    <>
      <DataTable loading columns={columns} data={[]} loadingRows={3} />
      <DataTable columns={columns} data={[]} />
    </>
  );
}

外观

variant / size / striped / hoverable / stickyHeader 组合出不同密度的表格。

	Role	Status
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Grace Hopper	admin	Paused	5

	Role	Status
Ada Lovelace	admin	Active	3
Alan Turing	editor	Active	2
Grace Hopper	admin	Paused	5

import { DataTable } from './components/elyri/DataTable';

export function Example() {
  return (
    <>
      <DataTable size="sm" striped columns={columns} data={members} />
      <DataTable variant="plain" hoverable columns={columns} data={members} />
    </>
  );
}

属性

属性	类型	默认值	说明
`columns`	`DataTableColumn<T>[]`	—	列定义数组
`data`	`T[]`	—	数据行数组
`getRowId`	`(row, index) => string`	—	行唯一键，默认取 row.id，缺失时回退到原始下标
`title`	`ReactNode`	—	工具栏左侧标题
`caption`	`ReactNode`	—	表格标题（caption）
`sort`	`DataTableSortState \| null`	—	受控排序状态，null 表示未排序
`defaultSort`	`DataTableSortState \| null`	—	非受控初始排序状态
`onSortChange`	`(sort) => void`	—	排序变化回调
`selectable`	`boolean`	`false`	显示行选择列
`selectedKeys`	`string[]`	—	受控选中行 key
`defaultSelectedKeys`	`string[]`	—	非受控初始选中行 key
`onSelectionChange`	`(keys) => void`	—	选中行变化回调
`searchable`	`boolean`	`false`	工具栏显示全局搜索框
`search`	`string`	—	受控搜索词
`onSearchChange`	`(value) => void`	—	搜索词变化回调
`globalFilterFn`	`(row, query) => boolean`	—	自定义全局搜索匹配
`pagination`	`boolean`	`true`	是否启用分页，默认 true
`page`	`number`	—	受控当前页（从 1 开始）
`onPageChange`	`(page) => void`	—	当前页变化回调
`pageSize`	`number`	`10`	每页条数
`pageSizeOptions`	`number[]`	—	每页条数选项，传入后显示选择器
`loading`	`boolean`	`false`	加载态，渲染骨架行
`loadingRows`	`number`	—	骨架行数，默认取当前每页条数
`empty`	`ReactNode`	—	自定义空状态内容
`variant`	`'outline' \| 'plain'`	`'outline'`	外观：'outline' \| 'plain'
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	行内边距与字号：'sm' \| 'md' \| 'lg'
`striped`	`boolean`	`false`	斑马纹
`hoverable`	`boolean`	`true`	悬停高亮，默认 true
`stickyHeader`	`boolean`	`false`	表头吸顶（需给容器设置高度或 maxHeight）
`toolbar`	`ReactNode`	—	工具栏右侧自定义内容
`labels`	`Partial<DataTableLabels>`	—	覆盖内置文案（搜索、全选、分页等）
`...rest`	`HTMLAttributes`	—	其余属性透传给原生 div

DataTable

安装

示例

基础用法#

排序#

全局搜索#

行选择#

分页#

加载与空状态#

外观#

属性

基础用法

排序

全局搜索

行选择

分页

加载与空状态

外观