Table

• 组件说明：数据表格组件，围绕数据驱动的 columns + dataSource API 设计。布局、对齐、空态、合并单元格等能力都应优先通过列和数据配置在组件层表达。
• 交互说明：支持行 hover 高亮、列对齐、表头排序控件、表头说明 tip 与空态占位。分页等业务交互由业务层承接。
• 实现约定：ui/table 仅保留结构骨架（滚动容器、边框、hover）；design 层在此基础上补充数据驱动渲染能力。
• Figma 参考

基础用法

传入 columns 和 dataSource 即可自动渲染表格，这是最简单的使用方式。

结果

Loading...

实时编辑器

render(
  <Table
    columns={[
      { title: '姓名', dataIndex: 'name', width: 160 },
      { title: '邮箱', dataIndex: 'email' },
      { title: '角色', dataIndex: 'role', width: 120 },
    ]}
    dataSource={[
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com', role: 'Owner' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'Editor' },
      { id: 3, name: 'Charlie Brown', email: 'charlie@example.com', role: 'Viewer' },
    ]}
    rowKey="id"
  />,
)

自定义单元格

通过列定义上的 render 函数自定义单元格内容。

结果

Loading...

实时编辑器

render(
  <Table
    columns={[
      { title: '名称', dataIndex: 'name', width: 160 },
      { title: '时长', dataIndex: 'duration', width: 100 },
      {
        title: '创建日期',
        dataIndex: 'createdAt',
        width: 180,
        render: (value) => new Date(String(value)).toLocaleDateString(),
      },
      {
        title: '',
        key: 'action',
        width: 60,
        align: 'center',
        render: () => (
          <button style={{ cursor: 'pointer', border: 'none', background: 'transparent' }}>
            ···
          </button>
        ),
      },
    ]}
    dataSource={[
      { id: 1, name: 'Meeting Notes', duration: '40m 39s', createdAt: '2026-03-10T17:47:03' },
      { id: 2, name: 'Project Review', duration: '25m 12s', createdAt: '2026-03-08T09:30:00' },
    ]}
    rowKey="id"
  />,
)

列对齐

列支持 left（默认）、center、right 三种对齐方式。

结果

Loading...

实时编辑器

render(
  <Table
    columns={[
      { title: '商品', dataIndex: 'item', align: 'left' },
      { title: '数量', dataIndex: 'qty', align: 'center', width: 100 },
      { title: '价格', dataIndex: 'price', align: 'right', width: 120 },
    ]}
    dataSource={[
      { id: 1, item: 'Plaud NotePin', qty: 2, price: '$169.00' },
      { id: 2, item: 'Plaud Note', qty: 1, price: '$159.00' },
    ]}
    rowKey="id"
  />,
)

嵌套字段

dataIndex 使用数组时，可以读取嵌套对象字段。

结果

Loading...

实时编辑器

render(
  <Table
    columns={[
      { title: '姓名', dataIndex: 'name' },
      { title: '城市', dataIndex: ['address', 'city'] },
      { title: '国家', dataIndex: ['address', 'country'] },
    ]}
    dataSource={[
      { id: 1, name: 'Alice', address: { city: 'Beijing', country: 'China' } },
      { id: 2, name: 'Bob', address: { city: 'Tokyo', country: 'Japan' } },
    ]}
    rowKey="id"
  />,
)

表头 Tip

在列定义里设置 tip，即可在表头渲染对齐 Figma 的帮助说明图标，并在 hover 时展示提示内容。

结果

Loading...

实时编辑器

render(
  <Table
    columns={[
      { title: '姓名', dataIndex: 'name', tip: '表格中展示给用户的主要名称。' },
      { title: '邮箱', dataIndex: 'email' },
      {
        title: '状态',
        dataIndex: 'status',
        tip: '状态字段来自最近一次审核结果同步。',
        width: 140,
      },
    ]}
    dataSource={[
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com', status: 'Active' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com', status: 'Pending' },
    ]}
    rowKey="id"
  />,
)

空态

通过 emptyText 在 dataSource 为空时展示占位内容。

结果

Loading...

实时编辑器

render(
  <Table
    columns={[
      { title: '姓名', dataIndex: 'name' },
      { title: '邮箱', dataIndex: 'email' },
    ]}
    dataSource={[]}
    emptyText="暂无数据"
  />,
)

Token 表

元素	属性	Token / 数值
表头	文字颜色	Labels/Tertiary#757575
表头	高度	40px (h-10)
表头	底部分割线	[&_tr]:border-b
行	Hover 背景	Backgrounds/Tertiary (50%)rgba(0,0,0,0.03)
行	选中背景	Backgrounds/Tertiaryrgba(0,0,0,0.05)
单元格	内边距	8px (p-2)
Footer	背景	Backgrounds/Tertiary (50%)rgba(0,0,0,0.03)

Props

Table（数据驱动）

Prop	Type	Default	Description
columns	TableColumnDef<T>[]	-	列定义
dataSource	T[]	-	数据数组
rowKey	string | ((record: T) => Key)	'key' 或 'id'	行唯一标识
emptyText	ReactNode	-	空数据时显示的内容
className	string	-	自定义样式类

TableColumnDef

Field	Type	Default	Description
key	string	-	列唯一 key，未传时回退到 dataIndex
dataIndex	string | string[]	-	数据字段路径，支持 ['address', 'city'] 这种嵌套路径
title	ReactNode	-	列头内容
tip	ReactNode	-	表头说明 tooltip 内容
sortable	boolean	auto	是否渲染排序能力
render	(value, record, index) => ReactNode	-	自定义单元格渲染
width	number | string	-	列宽
align	'left' | 'center' | 'right'	'left'	文本对齐方式
className	string	-	同时应用到 th 和 td 的列 className