组件 · 数据展示

LegacyTable 旧版表格（已废弃）

提供表格组合壳与引擎列模式；用于列表数据展示与分页联动。不是 DataTable/ProTable 业务框架，不内置 CRUD。

入口 @selrux/ui/legacy-table · 源码 src/components/legacy-table/index.ts · 9 个组件 · 发布状态 preview

使用建议

避免：杜撰 DataTable/ProTable API
避免：把 Table 当成完整业务 CRUD 引擎
限制：未标 stable；横向滚动或分组策略由页面模板明示
限制：引擎列泛型默认 RecordType=unknown，复杂列需断言

引入

tsx

123456789import {
  LegacyTable,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  // …共 12 个导出
} from '@selrux/ui/legacy-table';

场景归纳

表格区块是业务场景的组合，不等于一个 Table 组件。下面按可复用能力归纳；示例展示本库已提供的公开 API。

查询与浏览：排序、表头筛选、受控条件、分页、固定列、滚动、密度和列显隐。筛选同列多值取或，不同列取且；远程筛选由应用取数。
表格容器：TablePanel 组合标题与操作、查询工具、表格、整表状态与分页；相邻区域用细线分隔。TableHeader / TableBody / TableFooter 对应表格内部的 thead / tbody / tfoot；TableCaption 是表格说明，不代替面板标题或底部状态。滚动视口只裁切数据区。
选择与操作：页内全选、单选、跨页保留 key、批量工具栏与行操作。跨页全量选择需要服务端确认匹配范围，不应把当前页 selectedRows 当成全量记录。
内容与详情：状态、头像、链接、进度、比较值等富内容由列 render 组合已有 UI 组件；展开行通过 expandable 展示附加信息。
结构与合计：Header 对应 thead 分区，Head 对应 th 列标题，Row 对应 tr，Cell 对应 td，Footer 对应 tfoot，Caption 对应 caption。组合式直接使用这些部件；引擎通过 caption 与 summary 补充说明和按列合计。
布局规律：标题及工具在上，数据在中，合计或分页在下。采用细分隔线、低饱和状态、金额右对齐和等宽数字；size 同时控制字号、表头高度与单元格间距。scroll.y 默认启用固定表头，stickyHeader=false 可关闭。
编辑与反馈：单元格编辑、校验、保存、撤销、权限、错误反馈属于业务状态；Table 提供渲染位置和加载、空态基础表现。
大数据与特殊布局：分组小计可用组合式 Table 表达，权限矩阵可在单元格组合 Checkbox；这些业务状态由调用方维护。当前引擎不内置列拖动、列宽拖动、虚拟滚动、自动分组或树形行，不把普通滚动等同于虚拟化。

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

表格演练场示例数据
姓名	部门	年龄
用户 A	研发	28
用户 B	设计	32
用户 C	运营	25

代码演示

基础数据表

列定义、稳定 rowKey 与分页由 Table 引擎负责。

项目	负责人	状态
设计系统	产品组	进行中
控制中心	平台组	待发布
质量平台	质量组	已完成

账单结构

Header 是表头分区，Head 是列标题；Footer 合计按列对齐，Caption 提供表格说明。

最近三笔账单，金额单位为人民币。
账单	状态	付款方式	金额
INV001	已支付	信用卡	¥250.00
INV002	待支付	在线支付	¥150.00
INV003	未支付	银行转账	¥350.00
合计			¥750.00

组合式表格

静态指标直接组合语义表头与单元格。

各项目本周指标
指标	数值
请求数	12,408
成功率	99.2%

当前页合计

summary 接收筛选、排序、分页后的行；返回 TableRow，由引擎包裹 tfoot。

服务工时

筛选客户或翻页，查看本页合计

合计仅包含当前页；全量统计应由业务或服务端提供。
客户 Filter 产品组平台组		金额
产品组	2.5	¥750.00
平台组	4	¥1200.00
本页 2 笔	6.5	¥1950.00

分组小计

使用组合式 Table 表达分组行；折叠状态由示例管理，不假设引擎支持树形数据。

本周工时

按团队分组

示例工时；折叠只影响展示，合计始终包含全部任务。
任务	工时
· 2 项 · 18 小时
组件维护	12
文档补齐	6
· 2 项 · 12 小时
接口联调	8
日志巡检	4
全部任务	30

标题右侧主操作

展示表格主次信息与状态，同时保留本地创建示例。

站点

本地演示，最多创建 5 个站点

共 2 个站点

站点名称	状态	最近更新
产品文档docs.selrux.test	已发布	今天 10:24
团队门户team.selrux.test	草稿	昨天 16:08

标题右侧按钮组

ButtonGroup 切换任务范围，独立主按钮新增任务；窄屏可横向滚动查看操作。

交付任务

切换任务范围或添加本地示例任务

任务	状态
组件验收	进行中
文档同步	已完成

显示 2 / 2 项

自定义标题与描述

title/subtitle 接收行内 ReactNode，保留 h4、描述字号和上下布局；操作仍放右侧。

运行任务2 项

最近刷新 0 次 · 仅更新本地演示状态

任务	状态
组件验收	进行中
文档同步	已完成

日志面板

参考图中的标题、筛选、滚动表体与底部状态分别由 TablePanel 和语义 Table 组合。

运行日志

api.log · 9 Oct

12 条记录

行	时间	级别	来源	消息
1	00:00:05	Info	export-worker	Worker 158 picked up a job
2	00:00:29	Info	billing-sync	Session 313 refreshed
3	00:00:35	Warn	storage	Slow query took 895 ms
4	00:00:58	Info	scheduler	Worker 886 picked up a job
5	00:01:22	Info	ingest	Heartbeat from node 141
6	00:01:28	Info	api-gateway	Worker 380 picked up a job
7	00:01:51	Info	auth	Session 535 refreshed
8	00:02:14	Info	billing-sync	Heartbeat from node 690
9	00:02:21	Warn	search	Slow query took 209 ms
10	00:02:44	Error	export-worker	Export job failed after 3 retries
11	00:03:08	Warn	api-gateway	Rate limit reached for client 27
12	00:03:31	Info	scheduler	Queued job 409 for processing

显示 12 / 12 条记录滚动表格查看其余记录

完整容器

无可见标签的即时查询、右侧重置、语义表格合计及独立分页。

交付任务

按任务名称或分组查询

任务	分组	请求数
构建检查	前端	18
接口校验	服务端	24
文档同步	文档	12
本页合计		54

当前匹配 5 项；请求总数 101

数据引擎容器

描述位于标题下方，右侧按钮组控制列、刷新和密度，不显示搜索框。

运行任务

任务	负责人	状态
账号同步	身份服务	运行中
日志归档	存储服务	已完成
配置发布	配置服务	待处理

空结果容器

保留即时查询及汇总区，并在右侧提供重置入口恢复结果。

任务查询

空结果不会移除表格区域

任务
No data

匹配 0 项任务

排序与分页

比较函数做本地排序，页码由内置分页管理。

项目
Alpha	31
Beta	12

表头筛选

同一列可选多个值，Table 对本地数据执行筛选。

任务	状态筛选运行中待处理完成
构建任务	运行中
发布任务	待处理
巡检任务	完成

受控筛选

父级保存条件并回写，Table 根据 onFilter 筛本地数据。

名称	状态筛选启用停用
Alpha	启用
Beta	停用

列显隐

业务工具栏控制 hiddenColumnKeys，列 key 保持稳定。

项目	负责人	状态
Alpha	张三	进行中
Beta	李四	已完成

固定列与滚动

明确列宽后固定操作列，窄容器横向滚动。

任务	负责人	状态	更新日期
导入任务	张三	完成	2026-10-23
同步任务	李四	运行中	2026-10-24

紧凑密度

size 控制 Table 的基础行高和字号。

任务	状态
任务 1	正常
任务 2	正常
任务 3	正常
任务 4	正常
任务 5	正常
任务 6	正常

跨页选择

父级保存 key；selectedRows 只对应当前加载页，批量操作按 key 提交。

已选择 0 项：无

	姓名
	用户 A
	用户 B

单选行

适合选择一个关联记录，禁用项不能选中。

	环境
	生产环境
	归档环境

批量处理

受控选择驱动操作栏；已完成行禁选，提交仅更新本地演示数据。

待办任务

已选择 0 项

	任务	状态
	账单核对	待处理
	交付检查	待处理
	文档审核	已完成

选择待处理任务后可批量完成。

状态与进度

单元格组合 Badge、Progress、Button，任务推进由业务数据驱动。

交付进度

演示数据，点击推进增加 25%

进度与状态同步变化；完成后禁止继续推进。
任务	负责人	进度	状态
组件文档	设计系统组	75%	进行中
接口联调	平台组	25%	进行中
自动化检查	质量组	100%	已完成

权限矩阵

复选框表示业务权限，不使用 rowSelection；系统管理员行只读，所有更改仅留在本地。

固定表头

scroll.y 自动固定表头，可显式关闭；横向滚动时首尾固定列继续可见。

运行记录

滚动数据区查看固定表头与固定列

任务	负责人	日期	请求数
运行任务 01	产品组	2026-10-24	120
运行任务 02	平台组	2026-10-24	127
运行任务 03	产品组	2026-10-24	134
运行任务 04	平台组	2026-10-24	141
运行任务 05	产品组	2026-10-24	148
运行任务 06	平台组	2026-10-24	155
运行任务 07	产品组	2026-10-24	162
运行任务 08	平台组	2026-10-24	169
运行任务 09	产品组	2026-10-24	176
运行任务 10	平台组	2026-10-24	183
运行任务 11	产品组	2026-10-24	190
运行任务 12	平台组	2026-10-24	197
运行任务 13	产品组	2026-10-24	204
运行任务 14	平台组	2026-10-24	211
运行任务 15	产品组	2026-10-24	218
运行任务 16	平台组	2026-10-24	225
运行任务 17	产品组	2026-10-24	232
运行任务 18	平台组	2026-10-24	239
运行任务 19	产品组	2026-10-24	246
运行任务 20	平台组	2026-10-24	253
运行任务 21	产品组	2026-10-24	260
运行任务 22	平台组	2026-10-24	267
运行任务 23	产品组	2026-10-24	274
运行任务 24	平台组	2026-10-24	281

长文本与换行

保留完整说明，局部列样式允许断行；切换紧凑模式不会丢失内容。

任务说明

完整文本换行展示

任务	说明
缓存更新	配置发布后同步所有节点；如果部分节点离线，恢复连接后继续补偿。
构建检查	artifact_identifier_with_a_very_long_continuous_value_20261024_abcdefghijklmnopqrstuvwxyz
待补充	暂无说明

展开详情

每行按钮带展开状态，详情内容由业务传入。

	服务	负责人
	订单服务	平台组
最近部署：10 月 23 日；健康检查正常。
	文件服务	基础组

受控展开

父级限定同一时间只展开一行。

	请求
	请求 A
	请求 B

行内编辑

Table 只渲染单元格，编辑草稿与保存规则属于业务层。

项目	配额
Alpha
Beta

空态与边框

没有记录时仍保留表头和完整单元格跨度。

项目	状态
没有符合条件的记录

加载态

刷新时保留旧行，覆盖层显示加载反馈。

任务	状态
日报	已完成

远程排序

sorter=true 只回报条件，服务端负责返回排序后的当前页。

当前排序：默认

姓名
Alpha	28
Beta	36

API

属性覆盖：示例用到 7 / 29 个自有属性（24.1%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

LegacyTable.styles：语义 slot 内联样式，与 className/style 同类的样式逃生口，不单独演示

LegacyTable

迁移期旧表格根组件，使用与组合式 Table 不同的测试标记。

属性	说明	类型	默认值
`size`	-	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	-
`columns`	列定义；存在时启用引擎。	`TableColumnType<unknown>[]`	-
`dataSource`	数据源。	`readonly unknown[]`	-
`rowKey`	行主键。	`TableRowKey<unknown>`	-
`loading`	加载中。	`boolean`	-
`showHeader`	是否显示表头。	`boolean`	-
`bordered`	边框。	`boolean`	-
`locale`	文案。	`TableLocale`	-
`pagination`	分页；默认开启（对象默认值）。`false` 关闭。	`TablePaginationConfig`	-
`rowSelection`	行选择。	`TableRowSelection<unknown>`	-
`filterValues`	列筛选值；传入后由调用方控制。	`Readonly<Record<string, readonly string[]>>`	-
`defaultFilterValues`	非受控列筛选初始值。	`Readonly<Record<string, readonly string[]>>`	-
`onFilterValuesChange`	筛选值变化；远程数据源可据此重新取数。	`((values: TableFilterValues) => void)`	-
`hiddenColumnKeys`	隐藏的列 key；传入后由调用方控制。	`readonly string[]`	-
`expandable`	行详情展开；展开按钮由引擎渲染。	`TableExpandable<unknown>`	-
`scroll`	滚动。	`TableScroll`	-
`onChange`	分页 / 排序变化。无筛选值时 filters 为 `null`；否则返回当前筛选条件。	`((pagination: { current: number; pageSize: number; total: number; } \| null, filters: TableFilterValues \| null, sorter: TableSorterResult<unknown> \| TableSorterResult<unknown>[]) => void)`	-
`classNames`	语义 className。	`Partial<Record<TableSemanticSlot, string>> \| ((info: { props: TableProps<unknown>; }) => Partial<Record<TableSemanticSlot, string>>)`	-
`styles`	语义 style。	`Partial<Record<TableSemanticSlot, CSSProperties>> \| ((info: { props: TableProps<unknown>; }) => Partial<Record<TableSemanticSlot, CSSProperties>>)`	-
`components`	引擎可替换部件。	`TableEngineComponents`	-
`caption`	原生 caption；组合模式也可直接使用 TableCaption，二者择一。	`ReactNode`	-
`summary`	引擎专用：接收筛选、排序及分页后的当前页，返回 TableRow 子树，不包 TableFooter。	`((pageData: readonly unknown[]) => ReactNode)`	-
`tableProps`	原生 table 属性，用于可访问名称、布局及事件；不允许覆盖子树。	`Omit<TableHTMLAttributes<HTMLTableElement>, "children" \| "dangerouslySetInnerHTML">`	-
`stickyHeader`	固定表头；省略时随 scroll.y 启用，主题层负责外观。	`boolean`	-
`children`	组合壳子树。	`ReactNode`	-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

TableBody

主题化表体。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

TableCaption

主题化标题说明。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

TableCell

主题化单元格。

无自有属性；其余 289 项原生属性继承自 HTMLAttributes / TdHTMLAttributes。

TableFooter

主题化表尾。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

TableHead

主题化表头单元格。

无自有属性；其余 286 项原生属性继承自 HTMLAttributes / ThHTMLAttributes。

TableHeader

主题化表头。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

TablePanel

组织表格周边区域；标题与操作区在窄容器中保持单行，可通过键盘滚动查看溢出内容。

属性	说明	类型	默认值
`title`	面板标题，支持文本或行内 ReactNode；保留 h4 排版，过长时可横向滚动。	`ReactNode`	-
`subtitle`	标题下方的描述，支持文本或行内 ReactNode；独立行内显示，过长时可横向滚动。	`ReactNode`	-
`headerActions`	标题区域右侧的业务操作，可放按钮组；窄容器中保持单行并允许横向滚动。	`ReactNode`	-
`search`	查询栏左侧的筛选控件；可访问名称由调用方提供。	`ReactNode`	-
`tools`	查询栏右侧的重置、刷新、列设置及其他操作。	`ReactNode`	-
`summary`	跨列表格统计；按列对齐的合计应使用 TableFooter。	`ReactNode`	-
`pagination`	底部分页内容；传入时将内部 Table 的 pagination 设为 false。	`ReactNode`	-
`children` *	表格主体，可放组合式或列配置式 Table。	`ReactNode`	-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

TableRow

主题化行。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

导出类型：TableBodyProps、TableCaptionProps、TableCellProps、TableColumnType、TableEngineComponents、TableEngineProps、TableExpandable、TableFilterValues、TableFooterProps、TableHeaderProps、TableHeadProps、TableLocale、TablePaginationConfig、TablePanelProps、TableProps、TableRowProps、TableRowSelection、TableScroll、TableSemanticSlot、TableShellProps、TableSize、TableSorterResult、TableSortOrder

函数与常量

名称	说明	签名 / 类型
`createTableEngineComponents`	构造带样式的引擎 components。	`(size: TableSize) => TableEngineComponents`
`mergeTableComponents`	合并调用方 components 与默认 UI 配件。	`(size: TableSize, overrides?: TableEngineComponents) => TableEngineComponents`
`useTableSize`	读取最近 Table 尺寸。	`() => TableSize`

摘自源码 JSDoc。

LegacyTable.tableProps：原生 table 属性，用于可访问名称、布局及事件；不允许覆盖子树。
组织表格周边区域；标题与操作区在窄容器中保持单行，可通过键盘滚动查看溢出内容。
TablePanel.search：查询栏左侧的筛选控件；可访问名称由调用方提供。

状态与数据归属

有 columns 时启用引擎；不传 columns 时使用组合壳。引擎的筛选、排序、分页和展开状态均可受控；不要在一次挂载期间来回切换同一状态的控制方式。

本地数据：列提供 onFilter 时 Table 筛选 dataSource；sorter 为比较函数时本地排序；未给 pagination.total 时本地切页。
远程数据：列不提供 onFilter 时 Table 只上报筛选值；sorter=true 只上报排序；提供 pagination.total 时 dataSource 应为当前页结果。
列显隐通过 hiddenColumnKeys 由应用控制。列应提供稳定 key 或 dataIndex；不建议依赖序号生成的回退 key。
展开行详情只负责展示。需要异步加载、权限校验或失败重试时，由应用在 expandedRowRender 对应模块管理。
TablePanel 只负责布局，查询、工具、汇总及分页由业务提供。使用外部分页时，把内层引擎 Table 的 pagination 设为 false；组合式合计使用 TableFooter，引擎的 summary 返回 TableRow（不再包 TableFooter），跨列表说明放在 TablePanel 的 summary。
引擎 summary 接收当前页的数据，已经过本地筛选、排序与分页；无匹配时为空数组。远程分页不会计算全量合计。选择列、展开列及隐藏列变化时，调用方同步调整汇总单元格与 colSpan，确保列数一致。
两种模式均支持 scroll、stickyHeader、caption 与 tableProps。tableProps 的属性作用于原生 table，用 aria-label 指定名称；根组件的 className 和 style 仍作用于容器。caption 属性与 TableCaption 子组件择一使用；summary 仅适用于引擎。
TableCaption 是表格自身的标题说明，仍位于 table 内；面板标题请用 TablePanel 的 title。title 与 subtitle 支持行内 ReactNode，可组合图标、徽标或强调文本；默认 h4 与描述排版保留，不应嵌套标题、段落或块级容器。业务操作放 headerActions。TableRow、TableHead 和 TableCell 保持原来的表格语义与用法。
行内编辑、跨页批量操作、导出和删除等写操作由业务层处理验证、确认、失败与撤销，不把服务端数据所有权交给 Table。

角色	读取	编辑
系统管理员
内容编辑
访客

LegacyTable 旧版表格（已废弃）

使用建议

引入

场景归纳

演练场

代码演示

基础数据表

账单结构

组合式表格

当前页合计

服务工时

分组小计

本周工时

标题右侧主操作

站点

标题右侧按钮组

交付任务

自定义标题与描述

运行任务2 项

日志面板

运行日志

完整容器

交付任务

数据引擎容器

运行任务

空结果容器

任务查询

排序与分页

表头筛选

受控筛选

列显隐

固定列与滚动

紧凑密度

跨页选择

单选行

批量处理

待办任务

状态与进度

交付进度

权限矩阵

角色权限

固定表头

运行记录

长文本与换行

任务说明

展开详情

受控展开

行内编辑

空态与边框

加载态

远程排序

API

LegacyTable

TableBody

TableCaption

TableCell

TableFooter

TableHead

TableHeader

TablePanel

TableRow

函数与常量

无障碍

状态与数据归属