DataTable

提供高密度、可编辑的大型数据网格。中文惯用名：数据网格；适合高密度编辑与虚拟化。设计文档原名：DataTable。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.data-table`
名称	DataTable
二级分类	数据展示（`data-display`）
用途	提供高密度、可编辑的大型数据网格
描述	中文惯用名：数据网格；适合高密度编辑与虚拟化。设计文档原名：DataTable。

预览

静态结构：DataTable 根节点 data-slot="data-table"（relative），表格结构与 Table 一致（TableHeader / TableBody / TableRow / TableHead / TableCell）。sortable 列表头渲染 data-slot="data-table-sort" 按钮（未排序显示 ArrowUpDown 弱化图标，升 / 降序显示对应箭头），点击在 asc / desc 间切换并重置到第一页；filterable 列表头追加 data-slot="data-table-filter" 窄高筛选输入（客户端按单元格文本包含匹配，多列筛选同时生效）。单元格按 column.children（别名 renderChildren）子树经 Renderer 注入 { row, rowIndex } 渲染，否则取 row[column.key]（对象 JSON 序列化）。无数据行渲染 data-slot="table-empty"「暂无数据」；pagination.pageSize 存在时底部渲染 data-slot="table-pagination" 页码按钮。

DSL 结构

DslNode

{
  "type": "DataTable",
  "props": {
    "columns": [
      {
        "key": "name",
        "title": "页面"
      },
      {
        "key": "visits",
        "title": "访问量",
        "sortable": true
      },
      {
        "key": "trend",
        "title": "趋势"
      }
    ],
    "rows": [
      {
        "id": 1,
        "name": "首页",
        "visits": 12840,
        "trend": "上升"
      },
      {
        "id": 2,
        "name": "列表页",
        "visits": 8932,
        "trend": "持平"
      },
      {
        "id": 3,
        "name": "详情页",
        "visits": 6420,
        "trend": "上升"
      },
      {
        "id": 4,
        "name": "设置页",
        "visits": 2180,
        "trend": "下降"
      },
      {
        "id": 5,
        "name": "帮助中心",
        "visits": 1546,
        "trend": "持平"
      }
    ],
    "pagination": {
      "pageSize": 3
    }
  }
}

何时用

何时使用

在一个表格内同时需要排序、列筛选与分页：运营数据表、明细查询结果。
高密度数据浏览：列较多、行较多，用户需要快速定位与排序比较。
需要在表头以输入框做列级筛选（客户端包含匹配）而非跳转筛选表单。

何时不用

只需展示与简单分页、无需排序筛选：使用 Table，结构更轻。
单对象的字段集：使用 Descriptions；条目浏览型集合：使用 List。
需要真正的虚拟化、行内编辑与列拖拽等大数据网格能力：当前实现为客户端排序 / 筛选 / 分页，无虚拟滚动，超大结果集应在数据源侧分页。

变体

变体	视觉形态	适用场景
默认（无分页）	表头 + 全量数据行	行数可控的明细表
pagination 分页	底部页码按钮，按 pageSize 切片	数据量超过一屏的查询结果
sortable 排序	表头排序按钮 + 升降序箭头，点击切换并回到第一页	按数值或文本列快速排序比较
filterable 列筛选	表头下方窄高筛选输入，实时包含匹配	列级快速过滤（名称、负责人等）
自定义单元格	按 column.children 子树渲染，作用域含 row / rowIndex	单元格内渲染标签、进度等复合内容
空态	「暂无数据」占满整行	rows 为空或筛选后无匹配

API 属性

属性	类型	默认值	说明
`columns`	`DataTableColumn[]`	[]	列定义；项结构 { key, title?, sortable?, filterable?, children?: DslNode[], renderChildren?: DslNode[] }
`rows`	`Record<string, unknown>[]`	[]	数据行（通常为 ${data.xxx} 表达式解析结果）
`rowKey`	`string`	'id'	行 key 字段；缺失时回退行序号
`pagination`	`false	{ pageSize?: number }`	—
`sort`	`DataTableSort（{ key, order }）`	—	受控初始排序（order 为 asc / desc）；后续点击表头由组件内部维护
`onSort`	`(sort: DataTableSort) => void`	—	排序变化事件，传出 { key, order }（Renderer 绑定 events.onSort）
`onPageChange`	`(page: number) => void`	—	翻页事件，传出页码 number（Renderer 绑定 events.onPageChange）
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式

使用规范

只有需要排序 / 筛选 / 分页组合能力时才用 DataTable；纯展示集合用 Table 更低成本。
排序为客户端实现：数值列按数值比较，其余按字符串 localeCompare；大数据集应在数据源侧排序分页。
filterable 为客户端「包含匹配」且多列同时生效，适合快速定位；复杂筛选条件仍走筛选表单 + 数据源。
排序、筛选、翻页都会重置到第一页，联动数据源时把 onSort / onPageChange 的参数透传给查询。
列 key 必须唯一且与行字段名一致（无 children 模板时按 key 取值），否则单元格为空。

正例

✓ 访问量明细：columns 给 visits 开 sortable，点击表头按数值升降序，onSort 透传查询参数。
✓ 列级筛选：名称列 filterable，输入关键字实时过滤；配合 pagination 控制单页行数。
✓ 复合单元格：趋势列用 children 子树渲染 Tag，作用域取 ${row.trend} 着色。

反例

✕ 只需要展示与简单分页也用 DataTable（应使用 Table，减少不必要的交互面）。
✕ 把上万行数据一次性塞入 rows 期待虚拟化（实现无虚拟滚动，应在数据源侧分页）。
✕ 列 key 与行字段名不一致又未提供 children 模板，单元格渲染为空。

Design Token 映射

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