Table

按行列展示和操作结构化数据。中文惯用名：表格；与 DataTable、高级表格为不同层级的表格方案。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.table`
名称	Table
二级分类	数据展示（`data-display`）
用途	按行列展示和操作结构化数据
描述	中文惯用名：表格；与 DataTable、高级表格为不同层级的表格方案。

预览

静态结构：Table 根节点 data-slot="dsl-table"（relative），内为 vendored 表格原语（TableHeader / TableBody / TableRow / TableHead / TableCell）；列按 columns 顺序渲染，align 同时作用于表头与单元格（left 为默认不加类），width 透传为列宽。单元格默认取 row[dataIndex]（对象值经 JSON 序列化）或按 column.cell 子树经 Renderer 注入 { row, rowIndex } 渲染。loading 时叠加 data-slot="table-loading" 遮罩（bg-card/60 居中提示）；无数据行渲染 data-slot="table-empty"「暂无数据」；pagination.pageSize 存在时底部渲染 data-slot="table-pagination" 页码按钮（当前页实心）。

DSL 结构

DslNode

{
  "type": "Table",
  "props": {
    "columns": [
      {
        "title": "名称",
        "dataIndex": "name"
      },
      {
        "title": "负责人",
        "dataIndex": "owner"
      },
      {
        "title": "状态",
        "dataIndex": "status",
        "align": "center"
      }
    ],
    "dataSource": [
      {
        "id": 1,
        "name": "月度运营报告",
        "owner": "张三",
        "status": "已发布"
      },
      {
        "id": 2,
        "name": "客户分层方案",
        "owner": "李四",
        "status": "草稿"
      },
      {
        "id": 3,
        "name": "Q3 投放复盘",
        "owner": "王五",
        "status": "审核中"
      },
      {
        "id": 4,
        "name": "渠道增长分析",
        "owner": "赵六",
        "status": "已发布"
      }
    ],
    "pagination": {
      "pageSize": 5
    }
  }
}

何时用

何时使用

展示同构集合的结构化数据，需要按行列对齐阅读与比较：订单、成员、任务列表。
列定义稳定、需要按列对齐（数值右对齐、状态居中）与统一列宽。
数据量中等并需要简单分页（pagination.pageSize）或加载态（loading）。

何时不用

单对象的字段集：使用 Descriptions，Table 表达的是集合而非单个对象。
高密度编辑、列筛选 / 排序、虚拟化大数据网格：使用 DataTable。
条目以浏览识别为主、无需列对齐：使用 List，纵向列表更轻。
层级数据：使用 Tree；纯展示的指标单值：使用 Statistic。

变体

变体	视觉形态	适用场景
默认（无分页）	表头 + 数据行，全量渲染	数据量小、需一屏看完的表格
pagination 分页	底部页码按钮，按 pageSize 切片（当前页实心）	行数超过一屏的常规业务表格
align 列对齐	align=center / right 同时作用于表头与单元格	状态列居中、数值列右对齐的可读性优化
cell 自定义单元格	按 column.cell 子树渲染，作用域含 row / rowIndex	单元格内需要标签、按钮或条件样式
loading 加载中	半透明遮罩 + 居中加载文案覆盖表格	数据请求中，保持表头结构稳定
空态	「暂无数据」占满整行（colSpan 跨全部列）	dataSource 为空或筛选无结果

API 属性

属性	类型	默认值	说明
`columns`	`TableColumn[]`	[]	列定义（可含表达式解析后的数组）；项结构 { title?, dataIndex?, width?, align?, cell? }，cell 为行模板 DSL 子树
`dataSource`	`Record<string, unknown>[]`	[]	数据行（通常为 ${data.xxx} 表达式解析结果）
`rowKey`	`string`	'id'	行 key 字段；缺失时回退行序号
`loading`	`boolean`	false	加载中：叠加遮罩并展示加载文案
`pagination`	`false	{ pageSize?: number }`	—
`onChange`	`(pagination: TablePaginationInfo) => void`	—	翻页事件，传出 { current, pageSize, total }（Renderer 绑定 events.onChange）
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式

使用规范

列顺序按阅读优先级排列：标识列在左、数值与状态居中或右对齐、操作列在右。
align 与 width 配合使用：数值列右对齐便于纵向比较，状态列居中，长文本列给足宽度并截断。
分页为客户端切片：数据量较大时先经 data 源分页取数，避免一次性把全量数据塞进 dataSource。
空态必须可见：无数据时 Table 自带「暂无数据」占位，不要额外叠加 Empty 造成双重空态。
需要排序、列筛选或高密度编辑时改用 DataTable，不要在 Table 上自行拼装交互。

正例

✓ 订单列表：columns 定义订单号 / 金额（right）/ 状态（center），pagination { pageSize: 10 }。
✓ 任务表格：状态列用 cell 子树渲染 Tag，作用域取 ${row.status} 与 ${rowIndex}。
✓ 请求中：loading=true 覆盖表格，表头保持可见，减少布局跳动。

反例

✕ 用 Table 展示单个对象的字段集（应使用 Descriptions）。
✕ 需要列排序 / 筛选 / 虚拟化仍用 Table（应使用 DataTable）。
✕ dataSource 一次塞入上千行并期待 Table 自行虚拟化（实现为客户端分页，无虚拟滚动）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。