@apexhub/apex-ui-react 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +37 -2
  3. package/dist/en_US.d.ts +191 -0
  4. package/dist/index.cjs +40692 -0
  5. package/dist/index.d.ts +6869 -0
  6. package/dist/index.mjs +40676 -0
  7. package/dist/llm/alert.tokens.txt +44 -0
  8. package/dist/llm/alert.txt +167 -0
  9. package/dist/llm/apex-provider.txt +368 -0
  10. package/dist/llm/auto-complete.tokens.txt +77 -0
  11. package/dist/llm/auto-complete.txt +373 -0
  12. package/dist/llm/avatar.tokens.txt +38 -0
  13. package/dist/llm/avatar.txt +199 -0
  14. package/dist/llm/breadcrumb.tokens.txt +193 -0
  15. package/dist/llm/breadcrumb.txt +251 -0
  16. package/dist/llm/button.tokens.txt +470 -0
  17. package/dist/llm/button.txt +262 -0
  18. package/dist/llm/card.tokens.txt +27 -0
  19. package/dist/llm/card.txt +95 -0
  20. package/dist/llm/cascader.tokens.txt +253 -0
  21. package/dist/llm/cascader.txt +898 -0
  22. package/dist/llm/checkbox.tokens.txt +28 -0
  23. package/dist/llm/checkbox.txt +332 -0
  24. package/dist/llm/collapse.tokens.txt +84 -0
  25. package/dist/llm/collapse.txt +330 -0
  26. package/dist/llm/date-picker.tokens.txt +171 -0
  27. package/dist/llm/date-picker.txt +424 -0
  28. package/dist/llm/divider.tokens.txt +22 -0
  29. package/dist/llm/divider.txt +161 -0
  30. package/dist/llm/drawer.tokens.txt +71 -0
  31. package/dist/llm/drawer.txt +369 -0
  32. package/dist/llm/dropdown.tokens.txt +59 -0
  33. package/dist/llm/dropdown.txt +420 -0
  34. package/dist/llm/form.tokens.txt +26 -0
  35. package/dist/llm/form.txt +341 -0
  36. package/dist/llm/grid.txt +419 -0
  37. package/dist/llm/image.tokens.txt +28 -0
  38. package/dist/llm/image.txt +428 -0
  39. package/dist/llm/input-number.tokens.txt +159 -0
  40. package/dist/llm/input-number.txt +486 -0
  41. package/dist/llm/input.tokens.txt +136 -0
  42. package/dist/llm/input.txt +422 -0
  43. package/dist/llm/layout.tokens.txt +29 -0
  44. package/dist/llm/layout.txt +298 -0
  45. package/dist/llm/menu.tokens.txt +87 -0
  46. package/dist/llm/menu.txt +680 -0
  47. package/dist/llm/message.tokens.txt +25 -0
  48. package/dist/llm/message.txt +301 -0
  49. package/dist/llm/modal.tokens.txt +96 -0
  50. package/dist/llm/modal.txt +584 -0
  51. package/dist/llm/notification.tokens.txt +79 -0
  52. package/dist/llm/notification.txt +383 -0
  53. package/dist/llm/pagination.tokens.txt +33 -0
  54. package/dist/llm/pagination.txt +208 -0
  55. package/dist/llm/popover.tokens.txt +28 -0
  56. package/dist/llm/popover.txt +233 -0
  57. package/dist/llm/progress.tokens.txt +83 -0
  58. package/dist/llm/progress.txt +279 -0
  59. package/dist/llm/radio.tokens.txt +21 -0
  60. package/dist/llm/radio.txt +348 -0
  61. package/dist/llm/rate.tokens.txt +20 -0
  62. package/dist/llm/rate.txt +241 -0
  63. package/dist/llm/select.tokens.txt +160 -0
  64. package/dist/llm/select.txt +830 -0
  65. package/dist/llm/skeleton.tokens.txt +15 -0
  66. package/dist/llm/skeleton.txt +275 -0
  67. package/dist/llm/spin.tokens.txt +21 -0
  68. package/dist/llm/spin.txt +294 -0
  69. package/dist/llm/steps.tokens.txt +30 -0
  70. package/dist/llm/steps.txt +300 -0
  71. package/dist/llm/switch.tokens.txt +38 -0
  72. package/dist/llm/switch.txt +216 -0
  73. package/dist/llm/table.tokens.txt +94 -0
  74. package/dist/llm/table.txt +1046 -0
  75. package/dist/llm/tabs.tokens.txt +78 -0
  76. package/dist/llm/tabs.txt +306 -0
  77. package/dist/llm/tag.tokens.txt +76 -0
  78. package/dist/llm/tag.txt +305 -0
  79. package/dist/llm/tooltip.tokens.txt +22 -0
  80. package/dist/llm/tooltip.txt +304 -0
  81. package/dist/llm/tree-select.tokens.txt +174 -0
  82. package/dist/llm/tree-select.txt +762 -0
  83. package/dist/llm/tree.tokens.txt +36 -0
  84. package/dist/llm/tree.txt +505 -0
  85. package/dist/llm/typography.tokens.txt +60 -0
  86. package/dist/llm/typography.txt +413 -0
  87. package/dist/llm/upload.tokens.txt +201 -0
  88. package/dist/llm/upload.txt +706 -0
  89. package/dist/llms-full.txt +16689 -0
  90. package/dist/llms-theme.txt +32 -0
  91. package/dist/llms.txt +59 -0
  92. package/dist/locale/en_US.cjs +160 -0
  93. package/dist/locale/en_US.d.ts +4 -0
  94. package/dist/locale/en_US.mjs +161 -0
  95. package/dist/locale/zh_CN.cjs +160 -0
  96. package/dist/locale/zh_CN.d.ts +4 -0
  97. package/dist/locale/zh_CN.mjs +161 -0
  98. package/dist/style.css +19619 -0
  99. package/dist/zh_CN.d.ts +191 -0
  100. package/llms-full.txt +16689 -0
  101. package/llms-theme.txt +32 -0
  102. package/llms.txt +59 -0
  103. package/package.json +118 -3
  104. package/src/alert/llm.txt +167 -0
  105. package/src/alert/tokens.txt +44 -0
  106. package/src/apex-provider/llm.txt +368 -0
  107. package/src/auto-complete/llm.txt +373 -0
  108. package/src/auto-complete/tokens.txt +77 -0
  109. package/src/avatar/llm.txt +199 -0
  110. package/src/avatar/tokens.txt +38 -0
  111. package/src/breadcrumb/llm.txt +251 -0
  112. package/src/breadcrumb/tokens.txt +193 -0
  113. package/src/button/llm.txt +262 -0
  114. package/src/button/tokens.txt +470 -0
  115. package/src/card/llm.txt +95 -0
  116. package/src/card/tokens.txt +27 -0
  117. package/src/cascader/llm.txt +898 -0
  118. package/src/cascader/tokens.txt +253 -0
  119. package/src/checkbox/llm.txt +332 -0
  120. package/src/checkbox/tokens.txt +28 -0
  121. package/src/collapse/llm.txt +330 -0
  122. package/src/collapse/tokens.txt +84 -0
  123. package/src/date-picker/llm.txt +424 -0
  124. package/src/date-picker/tokens.txt +171 -0
  125. package/src/divider/llm.txt +161 -0
  126. package/src/divider/tokens.txt +22 -0
  127. package/src/drawer/llm.txt +369 -0
  128. package/src/drawer/tokens.txt +71 -0
  129. package/src/dropdown/llm.txt +420 -0
  130. package/src/dropdown/tokens.txt +59 -0
  131. package/src/form/llm.txt +341 -0
  132. package/src/form/tokens.txt +26 -0
  133. package/src/grid/llm.txt +419 -0
  134. package/src/image/llm.txt +428 -0
  135. package/src/image/tokens.txt +28 -0
  136. package/src/input/llm.txt +422 -0
  137. package/src/input/tokens.txt +136 -0
  138. package/src/input-number/llm.txt +486 -0
  139. package/src/input-number/tokens.txt +159 -0
  140. package/src/layout/llm.txt +298 -0
  141. package/src/layout/tokens.txt +29 -0
  142. package/src/menu/llm.txt +680 -0
  143. package/src/menu/tokens.txt +87 -0
  144. package/src/message/llm.txt +301 -0
  145. package/src/message/tokens.txt +25 -0
  146. package/src/modal/llm.txt +584 -0
  147. package/src/modal/tokens.txt +96 -0
  148. package/src/notification/llm.txt +383 -0
  149. package/src/notification/tokens.txt +79 -0
  150. package/src/pagination/llm.txt +208 -0
  151. package/src/pagination/tokens.txt +33 -0
  152. package/src/popover/llm.txt +233 -0
  153. package/src/popover/tokens.txt +28 -0
  154. package/src/progress/llm.txt +279 -0
  155. package/src/progress/tokens.txt +83 -0
  156. package/src/radio/llm.txt +348 -0
  157. package/src/radio/tokens.txt +21 -0
  158. package/src/rate/llm.txt +241 -0
  159. package/src/rate/tokens.txt +20 -0
  160. package/src/select/llm.txt +830 -0
  161. package/src/select/tokens.txt +160 -0
  162. package/src/skeleton/llm.txt +275 -0
  163. package/src/skeleton/tokens.txt +15 -0
  164. package/src/spin/llm.txt +294 -0
  165. package/src/spin/tokens.txt +21 -0
  166. package/src/steps/llm.txt +300 -0
  167. package/src/steps/tokens.txt +30 -0
  168. package/src/switch/llm.txt +216 -0
  169. package/src/switch/tokens.txt +38 -0
  170. package/src/table/llm.txt +1046 -0
  171. package/src/table/tokens.txt +94 -0
  172. package/src/tabs/llm.txt +306 -0
  173. package/src/tabs/tokens.txt +78 -0
  174. package/src/tag/llm.txt +305 -0
  175. package/src/tag/tokens.txt +76 -0
  176. package/src/tooltip/llm.txt +304 -0
  177. package/src/tooltip/tokens.txt +22 -0
  178. package/src/tree/llm.txt +505 -0
  179. package/src/tree/tokens.txt +36 -0
  180. package/src/tree-select/llm.txt +762 -0
  181. package/src/tree-select/tokens.txt +174 -0
  182. package/src/typography/llm.txt +413 -0
  183. package/src/typography/tokens.txt +60 -0
  184. package/src/upload/llm.txt +706 -0
  185. package/src/upload/tokens.txt +201 -0
@@ -0,0 +1,1046 @@
1
+ # Table
2
+
3
+ > Table:需要以行列形式展示、浏览结构化数据(列表、台账、报表)时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Table`、`TableSummary`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Table } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ const columns = [
19
+ { key: 'name', title: '姓名' },
20
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
21
+ { key: 'address', title: '地址' },
22
+ ]
23
+
24
+ const data = [
25
+ { key: '1', name: '张伟', age: 32, address: '北京市朝阳区' },
26
+ { key: '2', name: '李娜', age: 28, address: '上海市浦东新区' },
27
+ { key: '3', name: '王芳', age: 45, address: '广州市天河区' },
28
+ ]
29
+
30
+ export default () => <Table columns={columns} data={data} />
31
+ ```
32
+
33
+ ## 何时使用
34
+
35
+ - 需要以行列形式展示、浏览结构化数据(列表、台账、报表)时。
36
+ - 需要分页、行选择、展开子行、固定列或虚拟滚动等表格能力时。
37
+ - 若只需简单键值对展示或卡片列表,不必强行使用 Table。
38
+
39
+ ## API
40
+
41
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
42
+
43
+ 通用透传:
44
+ - `className` / `style` / `ref` → 包裹根 `<div>`
45
+ - `id` / `aria-label` 等 HTML 标准属性 → 内层 `<table>`
46
+
47
+ ### Table
48
+
49
+ 泛型参数:`<RecordType = Record<string, unknown>>`。
50
+
51
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
52
+ | --- | --- | --- | --- | --- |
53
+ | className | 追加到包裹根节点;组件内部已含 `apex-table`、`apex-default-table`、`apex-container-table`。<br>请追加而非整类替换,否则 `--table-fill-*` 等 token 可能失效。 | `string` | 否 | — |
54
+ | columns | 列定义 | `TableColumn<RecordType>[]` | 否 | `[]` |
55
+ | data | 数据;空数组渲染空态 | `RecordType[]` | 否 | `[]` |
56
+ | rowKey | 行键,映射到 TanStack `getRowId` | `RowKey<RecordType>` | 否 | `'key'` |
57
+ | loading | 加载态;普通表格用 3 行骨架占位,`scroll.y` / `flexHeight` 场景按表体可用高度自动填满。<br>骨架行高跟随 `size`(`--table-size-height-content` + block padding,视觉 28/32/40),加载时替换数据行。 | `boolean` | 否 | `false` |
58
+ | size | 尺寸;`small` / `medium` / `large` 对应 token 的 sm / md / la。<br>单元格内容区最小高度为 `--table-size-height-content`,加上 `--table-spacing-padding-y` 后视觉下限 28/32/40。<br>表体可继续被内容撑高,不锁死行高。<br>字号全 size 一致:表头 `text-*-body`(14/20),内容 `text-*-caption`(12/18)。<br>非 `ellipsis` 纯文本列可多行撑高;`ellipsis` 纯文本列保持单行截断。<br>- `small` — 紧凑<br>- `medium` — 标准<br>- `large` — 宽松(默认) | `"small" \| "medium" \| "large"` | 否 | `'large'` |
59
+ | showHeader | 是否渲染 `<thead>` | `boolean` | 否 | `true` |
60
+ | rowClassName | 行 className | `string \| ((record: RecordType, index: number) => string)` | 否 | — |
61
+ | onRow | 行原生属性透传 | `(record: RecordType, index: number) => React.HTMLAttributes<HTMLTableRowElement>` | 否 | — |
62
+ | pagination | 分页配置;`false` 关闭分页区 | `false \| TablePaginationConfig` | 否 | — |
63
+ | scroll | 内置滚动容器配置;设置后由 table 内部容器负责滚动。 | `TableScrollConfig` | 否 | — |
64
+ | flexHeight | 填充父容器高度:根节点变为 flex 列并占满父级可用高度,表体在内部容器纵向滚动、表头吸顶,分页固定在底部。<br>需父级为受限高度的 flex 容器(或给 Table 定高 / `flex: 1`)。<br>与 `scroll.y` 互斥,同时设置时以 `flexHeight` 为准(忽略 `scroll.y` 的 `max-height`)。 | `boolean` | 否 | `false` |
65
+ | virtual | 虚拟滚动:仅渲染可视窗口内的行,适用于大量数据。<br>需配合 `scroll.y` 或 `flexHeight` 提供受限高度容器;无受限高度时自动降级为非虚拟。<br>与 `mergeRows` / `cellSpan` 纵向合并不兼容(虚拟开启时跳过合并)。 | `boolean \| TableVirtualConfig` | 否 | `false` |
66
+ | rowSelection | 行选择配置;省略则不渲染选择列 | `TableRowSelection<RecordType>` | 否 | — |
67
+ | expandable | 行分组 / 展开配置;省略则不启用展开能力 | `TableExpandableConfig<RecordType>` | 否 | — |
68
+ | summary | 总结栏渲染函数。返回 `Table.Summary` 复合组件树,组件将其渲染为 `<tfoot>`。<br>入参 `currentData` 为当前页数据(开启分页时为分页切片)。 | `(currentData: RecordType[]) => React.ReactNode` | 否 | — |
69
+ | emptyText | 自定义空态内容(单表级)。<br>优先级:`emptyText` prop > `ApexProvider` 的 `locale.Table.emptyText` > 内置默认文案。 | `React.ReactNode` | 否 | — |
70
+ | hiddenColumnKeys | 受控隐藏列的 key 数组(列显隐机制)。<br>仅提供受控机制;触发器 UI / 持久化由消费方实现。prefix 列(选择 / 展开)不受影响。 | `Key[]` | 否 | — |
71
+ | defaultHiddenColumnKeys | 非受控初始隐藏列 key 数组。 | `Key[]` | 否 | `[]` |
72
+ | onHiddenColumnKeysChange | 隐藏列变化回调 | `(hiddenKeys: Key[]) => void` | 否 | — |
73
+ | columnOrder | 受控列顺序(按列 key 排列;列排序机制)。<br>**仅平铺列支持**:多级表头(含 `children` 的分组列)场景不支持列排序,显隐仍可用。<br>prefix 列(选择 / 展开)恒定排在最前,不进入此数组。 | `Key[]` | 否 | — |
74
+ | defaultColumnOrder | 非受控初始列顺序 | `Key[]` | 否 | — |
75
+ | onColumnOrderChange | 列顺序变化回调 | `(columnOrder: Key[]) => void` | 否 | — |
76
+ | ref | 包裹根 div 的 ref(React 19 直接作为 prop) | `React.Ref<HTMLDivElement>` | 否 | — |
77
+
78
+ ### TableEllipsisConfig
79
+
80
+ 列截断配置,与 `TypographyEllipsisConfig` 一致(`boolean | TypographyEllipsisConfig`)。
81
+
82
+ ```typescript
83
+ type TableEllipsisConfig = boolean | TypographyEllipsisConfig
84
+ ```
85
+
86
+ ### TableRowSelection
87
+
88
+ 泛型参数:`<RecordType = Record<string, unknown>>`。
89
+
90
+ 行选择配置。受控 / 非受控双轨;变化时同步触发 `onChange`。
91
+
92
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
93
+ | --- | --- | --- | --- | --- |
94
+ | type | 选中模式 | `"checkbox" \| "radio"` | 否 | `'checkbox'` |
95
+ | selectedRowKeys | 受控已选 row key 数组 | `Key[]` | 否 | — |
96
+ | defaultSelectedRowKeys | 非受控初始已选 row key 数组 | `Key[]` | 否 | `[]` |
97
+ | columnWidth | 选择列宽 | `number \| string` | 否 | `48(`showIndex` 为 true)/ 40(`showIndex` 为 false)` |
98
+ | hideSelectAll | 是否隐藏全选 checkbox(仅 `checkbox` 模式) | `boolean` | 否 | `false` |
99
+ | showIndex | 是否将序号与选择列合并:默认显示序号,行 hover / 已选 / 键盘焦点时切换为选择控件。<br>序号按当前页连续编号(分页时为全局序号:`(current - 1) * pageSize + index + 1`)。 | `boolean` | 否 | `true` |
100
+ | fixed | 固定选择列方向;须配合 `scroll.x` 与数字 `columnWidth` 使用 | `"left" \| "right"` | 否 | — |
101
+ | onChange | 选中变化回调 | `(selectedRowKeys: Key[], selectedRows: RecordType[]) => void` | 否 | — |
102
+ | getCheckboxProps | 单行禁用配置 | `(record: RecordType) => { disabled?: boolean }` | 否 | — |
103
+
104
+ ### TableExpandIconProps
105
+
106
+ 泛型参数:`<RecordType = Record<string, unknown>>`。
107
+
108
+ 展开图标 render props(面板 / 树形共用)。
109
+
110
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
111
+ | --- | --- | --- | --- | --- |
112
+ | expanded | — | `boolean` | 是 | — |
113
+ | onExpand | — | `(event: React.MouseEvent<HTMLElement>) => void` | 是 | — |
114
+ | record | — | `RecordType` | 是 | — |
115
+
116
+ ### TableExpandableConfig
117
+
118
+ 泛型参数:`<RecordType = Record<string, unknown>>`。
119
+
120
+ 行分组 / 展开配置。
121
+
122
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
123
+ | --- | --- | --- | --- | --- |
124
+ | childrenColumnName | 嵌套子行字段名(树形模式) | `string` | 否 | `'children'` |
125
+ | columnTitle | 展开列表头 | `React.ReactNode` | 否 | — |
126
+ | columnWidth | 展开列宽(面板模式) | `number \| string` | 否 | `48` |
127
+ | indentSize | 树形缩进像素(树形模式) | `number` | 否 | `15` |
128
+ | expandedRowKeys | 受控已展开 row key 数组 | `Key[]` | 否 | — |
129
+ | defaultExpandedRowKeys | 非受控初始已展开 row key 数组 | `Key[]` | 否 | `[]` |
130
+ | expandedRowRender | 展开行自定义面板(面板模式) | `( record: RecordType, index: number, indent: number, expanded: boolean, ) => React.ReactNode` | 否 | — |
131
+ | expandIcon | 自定义展开图标 | `(props: TableExpandIconProps<RecordType>) => React.ReactNode` | 否 | — |
132
+ | expandRowByClick | 点击整行展开/收起(面板模式) | `boolean` | 否 | `false` |
133
+ | rowExpandable | 行是否可展开 | `(record: RecordType) => boolean` | 否 | — |
134
+ | showExpandColumn | 是否显示展开列(面板模式) | `boolean` | 否 | `true` |
135
+ | expandedRowClassName | 展开面板行 className | `string \| ((record: RecordType, index: number, indent: number) => string)` | 否 | — |
136
+ | fixed | 固定展开列方向(面板模式) | `"left" \| "right"` | 否 | — |
137
+ | onExpand | 展开/收起单行回调 | `(expanded: boolean, record: RecordType) => void` | 否 | — |
138
+ | onExpandedRowsChange | 已展开 keys 变化回调 | `(expandedKeys: Key[]) => void` | 否 | — |
139
+
140
+ ### TableColumn
141
+
142
+ 泛型参数:`<RecordType = Record<string, unknown>>`。
143
+
144
+ 单列定义。
145
+
146
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
147
+ | --- | --- | --- | --- | --- |
148
+ | key | 列标识;数组形式表示深路径 | `DataIndex` | 否 | — |
149
+ | title | 表头单元格 | `React.ReactNode` | 否 | — |
150
+ | renderHeader | 自定义列头渲染回调。返回值作为表头内容,优先级高于 `title`。<br>入参为当前列定义(含已声明的 `title` / `key` / `align` 等),便于在默认标题外附加图标/排序/操作。<br>分组列(含 `children`)同样适用,渲染其父表头。<br>注:参数采用非泛型列定义,避免列类型对 `RecordType` 不变(invariant)。 | `(column: TableColumn) => React.ReactNode` | 否 | — |
151
+ | render | 自定义单元格 | `(text: unknown, record: RecordType, index: number) => React.ReactNode` | 否 | — |
152
+ | align | 单元格对齐 | `"left" \| "right" \| "center"` | 否 | `'left'` |
153
+ | className | 列 className(写到 td/th 上) | `string` | 否 | — |
154
+ | width | 列宽 | `string \| number` | 否 | — |
155
+ | minWidth | 列最小宽 | `number` | 否 | `50` |
156
+ | ellipsis | 截断模式,API 与 `Typography.Text` 的 `ellipsis` 一致。<br>- `true`:单行截断,Table 层默认溢出 Tooltip(等价 `{ rows: 1, tooltip: true }`)。<br>- `{ rows: 1 }`:单行截断,**无**默认 Tooltip;`\n` 折叠为空格,不启用硬换行。<br>- `{ rows: N }` 当 **N ≥ 2**:多行 `-webkit-line-clamp`;`\n` 计入视觉行数。<br>含 `\n` 且需控行高时推荐 `{ rows: 2, tooltip: true }` 起(见 `index.md` D15)。<br>- 对象形态可细调 `tooltip`、`rows`、`position` 等。<br>仅对**纯文本**(string / number)内容生效;当 `render` 返回 ReactNode(组件)时<br>自动转为**弹性高度**:不截断、行高随内容自适应。 | `TableEllipsisConfig` | 否 | `false` |
157
+ | onCell | 单元格原生属性透传(不承载合并语义)。 | `(record: RecordType, rowIndex: number) => React.HTMLAttributes<HTMLTableCellElement>` | 否 | — |
158
+ | mergeRows | 纵向合并相邻相同值。`true` 按列取值比较;函数返回分组键比较。<br>组件自动计算 `rowSpan` 并跳过被覆盖格。与 `cellSpan` 同时存在时以 `cellSpan` 为准。 | `boolean \| ((record: RecordType, index: number) => Key)` | 否 | — |
159
+ | cellSpan | 不规则 / 横向合并逃生口。仅在起点返回 `rowSpan` / `colSpan`。<br>跨度仅接受有限正整数;非法值按 `1` 处理,超出范围时分别截断到当前页剩余行数<br>和剩余可见叶子列数。组件按占位矩阵自动跳过被覆盖格。 | `( record: RecordType, index: number, ) => { rowSpan?: number; colSpan?: number } \| undefined` | 否 | — |
160
+ | colSpan | 表头同行内叶子列横向合并跨度。仅接受有限正整数;非法值按 `1` 处理,<br>超出范围时截断到剩余可见叶子列数。起点列声明即可,被覆盖列自动跳过。 | `number` | 否 | — |
161
+ | children | 多级表头:带 `children` 即为分组列,`title` 作父表头;仅叶子列承载数据与 body 合并。 | `TableColumn<RecordType>[]` | 否 | — |
162
+ | fixed | 固定列方向。固定列必须提供数字 `width`(像素),且需配合 `scroll.x` 使用。 | `"left" \| "right"` | 否 | — |
163
+
164
+ ### TablePaginationConfig
165
+
166
+ 分页配置,与 Apex `PaginationProps` 完全对齐。
167
+
168
+ **类型别名**:`TablePaginationConfig` 即 `PaginationProps`,与 Pagination 组件的 `PaginationProps` 相同(可从 `@apexhub/apex-ui-react` 导入)。
169
+
170
+ 等价写法:`TablePaginationConfig` ≡ `PaginationProps`
171
+
172
+ ### TableVirtualConfig
173
+
174
+ 虚拟滚动配置。
175
+
176
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
177
+ | --- | --- | --- | --- | --- |
178
+ | itemSize | 预估行高(px),用于初始定位;实际高度由动态测量校正。<br>默认按 `size` 推导:small=28 / medium=32 / large=40 | `number` | 否 | — |
179
+ | overscan | 视口外预渲染行数 | `number` | 否 | `6` |
180
+
181
+ ### TableSummaryFixed
182
+
183
+ 总结栏固定位置。`true` 等价于 `'bottom'`。
184
+
185
+ ```typescript
186
+ type TableSummaryFixed = boolean | 'top' | 'bottom'
187
+ ```
188
+
189
+ ### TableSummaryProps
190
+
191
+ `Table.Summary` 根节点 props。
192
+
193
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
194
+ | --- | --- | --- | --- | --- |
195
+ | fixed | 总结栏位置。`true` 或 `'bottom'` 时钉在表体容器底部(需 `scroll.y` / `flexHeight` / `virtual`);内容不够高时合计与数据行之间留白。`'top'` 为吸顶。 | `TableSummaryFixed` | 否 | `false` |
196
+ | className | 追加 className | `string` | 否 | — |
197
+ | children | — | `React.ReactNode` | 否 | — |
198
+
199
+ ### TableSummaryRowProps
200
+
201
+ 继承:`React.HTMLAttributes<HTMLTableRowElement>`;本节列出新增或重声明字段。
202
+
203
+ `Table.Summary.Row` props。
204
+
205
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
206
+ | --- | --- | --- | --- | --- |
207
+ | children | — | `React.ReactNode` | 否 | — |
208
+
209
+ ### TableSummaryCellProps
210
+
211
+ 继承:`React.HTMLAttributes<HTMLTableCellElement>`;本节列出新增或重声明字段。
212
+
213
+ `Table.Summary.Cell` props。
214
+
215
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
216
+ | --- | --- | --- | --- | --- |
217
+ | index | 对应叶子列索引(含选择列 / 展开列等 prefix 列)。 | `number` | 是 | — |
218
+ | colSpan | 横向合并跨度(>= 2)。 | `number` | 否 | — |
219
+ | rowSpan | 纵向合并跨度(>= 2)。 | `number` | 否 | — |
220
+ | align | 单元格对齐;未指定时继承对应叶子列的 `align`。 | `"left" \| "right" \| "center"` | 否 | `'left'` |
221
+ | children | — | `React.ReactNode` | 否 | — |
222
+
223
+ ### TableScrollConfig
224
+
225
+ 内置滚动容器配置。
226
+
227
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
228
+ | --- | --- | --- | --- | --- |
229
+ | x | 横向滚动宽度;设置后,表格内部容器负责横向滚动。 | `number \| string` | 否 | — |
230
+ | y | 纵向滚动高度;设置后,表格内部容器负责纵向滚动,表头吸顶。 | `number \| string` | 否 | — |
231
+
232
+ ### Key
233
+
234
+ ```typescript
235
+ type Key = string | number
236
+ ```
237
+
238
+ ### DataIndex
239
+
240
+ ```typescript
241
+ type DataIndex = string | readonly string[]
242
+ ```
243
+
244
+ ### AlignValue
245
+
246
+ ```typescript
247
+ type AlignValue = 'left' | 'center' | 'right'
248
+ ```
249
+
250
+ ### RowKey
251
+
252
+ 泛型参数:`<RecordType>`。
253
+
254
+ ```typescript
255
+ type RowKey<RecordType> = string | keyof RecordType | ((record: RecordType, index: number) => Key)
256
+ ```
257
+
258
+ 其他组件的类型不在此展开:`TypographyEllipsisConfig` 见 `../typography/llm.txt`、`PaginationProps` 见 `../pagination/llm.txt`。
259
+
260
+ ### 导出类型
261
+
262
+ 另可从 `@apexhub/apex-ui-react` 导入:`AlignValue`、`DataIndex`、`EllipsisConfig`、`Key`、`PaginationState`、`RowKey`、`TableColumn`、`TablePaginationConfig`、`TableProps`、`TableRowSelection`、`TableSummaryCellProps`、`TableSummaryFixed`、`TableSummaryLeafColumn`、`TableSummaryProps`、`TableSummaryRowProps`、`TableVirtualConfig`(与上文子类型配合使用)。
263
+
264
+ ## 代码演示
265
+
266
+ ### 尺寸
267
+
268
+ 通过 `size` 切换密度:表头最小高度 `small`(28px)/ `medium`(32px)/ `large`(40px,默认);表体行高由内容撑开。字号在各档保持一致:表头 14px、内容 12px。
269
+
270
+ ```tsx
271
+ import { Table } from '@apexhub/apex-ui-react'
272
+
273
+ const columns = [{ key: 'name', title: '姓名' }]
274
+
275
+ const data = [{ key: '1', name: '示例' }]
276
+
277
+ export default () => (
278
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
279
+ <Table columns={columns} data={data} size="small" />
280
+ <Table columns={columns} data={data} size="medium" />
281
+ <Table columns={columns} data={data} size="large" />
282
+ </div>
283
+ )
284
+ ```
285
+
286
+ ### 加载中
287
+
288
+ `loading` 为 `true` 时显示骨架屏加载态。骨架行高跟随 `size`,各行列宽保持一致,固定高度与自适应高度表格都能完整填充内容区。
289
+
290
+ ```tsx
291
+ import { Table } from '@apexhub/apex-ui-react'
292
+
293
+ const columns = [
294
+ { key: 'name', title: '姓名' },
295
+ { key: 'status', title: '状态' },
296
+ ]
297
+
298
+ const data = [{ key: '1', name: '加载中示例', status: '处理中' }]
299
+
300
+ export default () => <Table columns={columns} data={data} loading />
301
+ ```
302
+
303
+ ### 空数据
304
+
305
+ `data` 为空数组时渲染空态;可用 `emptyText` 覆盖默认文案或传入自定义节点。
306
+
307
+ ```tsx
308
+ import { Table } from '@apexhub/apex-ui-react'
309
+
310
+ const columns = [
311
+ { key: 'name', title: '姓名' },
312
+ { key: 'age', title: '年龄' },
313
+ { key: 'address', title: '地址' },
314
+ ]
315
+
316
+ export default () => <Table columns={columns} data={[]} />
317
+ ```
318
+
319
+ ### 自定义空态
320
+
321
+ `emptyText` 支持任意 `自定义节点`,可嵌入操作按钮或插画。
322
+
323
+ ```tsx
324
+ import { Button, Table } from '@apexhub/apex-ui-react'
325
+
326
+ const columns = [
327
+ { key: 'name', title: '姓名' },
328
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
329
+ { key: 'address', title: '地址' },
330
+ ]
331
+
332
+ export default () => (
333
+ <Table
334
+ columns={columns}
335
+ data={[]}
336
+ emptyText={
337
+ <div style={{ padding: '24px 0' }}>
338
+ <p style={{ margin: 0 }}>暂无符合条件的记录</p>
339
+ <Button type="primary" style={{ marginTop: 8 }}>
340
+ 去创建
341
+ </Button>
342
+ </div>
343
+ }
344
+ />
345
+ )
346
+ ```
347
+
348
+ ### 分页
349
+
350
+ 通过 `pagination` 配置分页;设为 `false` 可关闭分页区。内嵌分页器保留 Pagination 自身的 36px 高度与容器留白,开启 `showSizeChanger` 或 `showQuickJumper` 时仍与独立 Pagination 保持一致。
351
+
352
+ ```tsx
353
+ import { Table } from '@apexhub/apex-ui-react'
354
+
355
+ const columns = [
356
+ { key: 'name', title: '姓名' },
357
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
358
+ { key: 'address', title: '地址' },
359
+ ]
360
+
361
+ const data = Array.from({ length: 23 }, (_, i) => ({
362
+ key: String(i + 1),
363
+ name: `用户 ${i + 1}`,
364
+ age: 20 + (i % 30),
365
+ address: `城市 ${i + 1} 区`,
366
+ }))
367
+
368
+ export default () => (
369
+ <Table
370
+ columns={columns}
371
+ data={data}
372
+ pagination={{ defaultPageSize: 10, showSizeChanger: true }}
373
+ />
374
+ )
375
+ ```
376
+
377
+ ### 纵向滚动
378
+
379
+ 通过 `scroll.y` 限制表体高度,由表格内部容器负责纵向滚动,表头吸顶。
380
+
381
+ ```tsx
382
+ import { Table } from '@apexhub/apex-ui-react'
383
+
384
+ const columns = [
385
+ { key: 'name', title: '姓名' },
386
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
387
+ { key: 'address', title: '地址' },
388
+ ]
389
+
390
+ const data = Array.from({ length: 50 }, (_, i) => ({
391
+ key: String(i + 1),
392
+ name: `用户 ${String(i + 1).padStart(3, '0')}`,
393
+ age: 18 + (i % 50),
394
+ address: `城市 ${(i % 10) + 1} 区 街道 ${i + 1} 号`,
395
+ }))
396
+
397
+ export default () => (
398
+ <Table columns={columns} data={data} size="small" pagination={false} scroll={{ y: 300 }} />
399
+ )
400
+ ```
401
+
402
+ ### 横向滚动
403
+
404
+ 当列总宽超出容器时,通过 `scroll.x` 开启横向滚动;固定列须配合 `scroll.x` 与数字 `width` 使用。
405
+
406
+ ```tsx
407
+ import { Table } from '@apexhub/apex-ui-react'
408
+
409
+ const columns = [
410
+ { key: 'id', title: 'ID', width: 80 },
411
+ { key: 'name', title: '姓名', width: 120 },
412
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
413
+ { key: 'email', title: '邮箱', width: 200 },
414
+ { key: 'department', title: '部门', width: 140 },
415
+ { key: 'city', title: '城市', width: 120 },
416
+ { key: 'address', title: '地址', width: 240 },
417
+ { key: 'status', title: '状态', width: 100 },
418
+ ]
419
+
420
+ const data = Array.from({ length: 8 }, (_, index) => ({
421
+ key: String(index + 1),
422
+ id: index + 1,
423
+ name: `用户 ${String(index + 1).padStart(3, '0')}`,
424
+ age: 22 + (index % 20),
425
+ email: `user${index + 1}@example.com`,
426
+ department: `部门 ${(index % 4) + 1}`,
427
+ city: `城市 ${(index % 5) + 1}`,
428
+ address: `街道 ${index + 1} 号`,
429
+ status: index % 2 === 0 ? '在职' : '离职',
430
+ }))
431
+
432
+ export default () => (
433
+ <Table
434
+ columns={columns}
435
+ data={data}
436
+ size="small"
437
+ pagination={false}
438
+ scroll={{ x: 1100 }}
439
+ style={{ width: 600 }}
440
+ />
441
+ )
442
+ ```
443
+
444
+ ### 行选择
445
+
446
+ 配置 `rowSelection` 开启多选或单选列。默认将**序号与选择列合并**:单元格显示行号,鼠标悬停当前行(或已选 / 键盘焦点)时切换为复选框;点击即可选中。设 `showIndex: false` 可恢复为始终显示选择控件。分页开启时序号为全局连续编号。
447
+
448
+ ```tsx
449
+ import { Table } from '@apexhub/apex-ui-react'
450
+
451
+ import { useState } from 'react'
452
+
453
+ const columns = [
454
+ { key: 'name', title: '姓名' },
455
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
456
+ { key: 'address', title: '地址' },
457
+ ]
458
+
459
+ const data = [
460
+ { key: '1', name: '张伟', age: 32, address: '北京市朝阳区' },
461
+ { key: '2', name: '李娜', age: 28, address: '上海市浦东新区' },
462
+ { key: '3', name: '王芳', age: 45, address: '广州市天河区' },
463
+ ]
464
+
465
+ export default () => {
466
+ const [selectedKeys, setSelectedKeys] = useState<Array<string | number>>(['2'])
467
+
468
+ return (
469
+ <Table
470
+ columns={columns}
471
+ data={data}
472
+ rowSelection={{
473
+ selectedRowKeys: selectedKeys,
474
+ onChange: (nextKeys) => setSelectedKeys(nextKeys),
475
+ }}
476
+ />
477
+ )
478
+ }
479
+ ```
480
+
481
+ ### 固定选择列
482
+
483
+ `rowSelection.fixed` 可将选择列固定在左侧或右侧;须配合 `scroll.x` 与数字 `columnWidth` 使用。与 `column.fixed: 'left'` 叠加时,选择列始终在最左并参与偏移计算。
484
+
485
+ 本例设置 `rowSelection.showIndex: false`,复选框始终显示,无需悬停行。
486
+
487
+ ```tsx
488
+ import { Button, Table } from '@apexhub/apex-ui-react'
489
+
490
+ import { useState } from 'react'
491
+
492
+ const columns = [
493
+ { key: 'name', title: '姓名', width: 100, fixed: 'left' as const },
494
+ { key: 'department', title: '部门', width: 100 },
495
+ { key: 'city', title: '城市', width: 100 },
496
+ { key: 'phone', title: '电话', width: 160 },
497
+ { key: 'email', title: '邮箱', width: 200 },
498
+ {
499
+ key: 'action',
500
+ title: '操作',
501
+ width: 80,
502
+ align: 'center' as const,
503
+ fixed: 'right' as const,
504
+ render: () => (
505
+ <Button
506
+ type="text"
507
+ size="small"
508
+ style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 0 }}
509
+ >
510
+ 编辑
511
+ </Button>
512
+ ),
513
+ },
514
+ ]
515
+
516
+ const data = Array.from({ length: 8 }, (_, i) => ({
517
+ key: String(i + 1),
518
+ name: `用户 ${i + 1}`,
519
+ department: '研发部',
520
+ city: '上海',
521
+ phone: '13800000000',
522
+ email: `user${i + 1}@example.com`,
523
+ }))
524
+
525
+ export default () => {
526
+ const [selectedKeys, setSelectedKeys] = useState<Array<string | number>>([])
527
+
528
+ return (
529
+ <div style={{ width: 700 }}>
530
+ <Table
531
+ columns={columns}
532
+ data={data}
533
+ scroll={{ x: 900 }}
534
+ pagination={false}
535
+ rowSelection={{
536
+ fixed: 'left',
537
+ showIndex: false,
538
+ columnWidth: 48,
539
+ selectedRowKeys: selectedKeys,
540
+ onChange: (keys) => setSelectedKeys(keys),
541
+ }}
542
+ />
543
+ </div>
544
+ )
545
+ }
546
+ ```
547
+
548
+ ### 文本截断与 Tooltip
549
+
550
+ 纯文本列设置 `ellipsis: { tooltip: true }` 时,内容溢出后 hover 弹出 Tooltip 显示完整文本。
551
+
552
+ ```tsx
553
+ import { Table } from '@apexhub/apex-ui-react'
554
+
555
+ const columns = [
556
+ { key: 'name', title: '姓名', width: 80 },
557
+ {
558
+ key: 'address',
559
+ title: '地址',
560
+ width: 120,
561
+ ellipsis: { tooltip: true },
562
+ },
563
+ ]
564
+
565
+ const data = [
566
+ {
567
+ key: '1',
568
+ name: '张伟',
569
+ address:
570
+ '北京市朝阳区某某街道某某社区某某大厦 1234 号楼 5678 室(超长地址用于触发截断与 Tooltip)',
571
+ },
572
+ ]
573
+
574
+ export default () => (
575
+ <div style={{ width: 240 }}>
576
+ <Table columns={columns} data={data} pagination={false} />
577
+ </div>
578
+ )
579
+ ```
580
+
581
+ ### 列显隐
582
+
583
+ 通过 `hiddenColumnKeys` / 列显隐变化事件 受控隐藏列;选择列、展开列不受影响。
584
+
585
+ ```tsx
586
+ import { Button, Table } from '@apexhub/apex-ui-react'
587
+
588
+ import { useState } from 'react'
589
+
590
+ const columns = [
591
+ { key: 'name', title: '姓名' },
592
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
593
+ { key: 'address', title: '地址' },
594
+ ]
595
+
596
+ const data = [
597
+ { key: '1', name: '张伟', age: 32, address: '北京市朝阳区' },
598
+ { key: '2', name: '李娜', age: 28, address: '上海市浦东新区' },
599
+ ]
600
+
601
+ export default () => {
602
+ const [hidden, setHidden] = useState<Array<string | number>>(['age'])
603
+
604
+ return (
605
+ <div>
606
+ <Button
607
+ style={{ marginBottom: 12 }}
608
+ onClick={() =>
609
+ setHidden((prev) =>
610
+ prev.includes('age') ? prev.filter((k) => k !== 'age') : [...prev, 'age'],
611
+ )
612
+ }
613
+ >
614
+ 切换「年龄」列
615
+ </Button>
616
+ <Table
617
+ columns={columns}
618
+ data={data}
619
+ pagination={false}
620
+ hiddenColumnKeys={hidden}
621
+ onHiddenColumnKeysChange={setHidden}
622
+ />
623
+ </div>
624
+ )
625
+ }
626
+ ```
627
+
628
+ ### 自定义渲染
629
+
630
+ 通过 `column.render` 自定义单元格内容。
631
+
632
+ ```tsx
633
+ import type { TableColumn } from '@apexhub/apex-ui-react'
634
+
635
+ import { Button, Table, Tag } from '@apexhub/apex-ui-react'
636
+
637
+ type OrderRecord = {
638
+ key: string
639
+ order: string
640
+ customer: string
641
+ amount: number
642
+ status: 'paid' | 'pending' | 'refunded'
643
+ }
644
+
645
+ const data: OrderRecord[] = [
646
+ { key: '1', order: 'SO-202605-001', customer: '张伟', amount: 1280, status: 'paid' },
647
+ { key: '2', order: 'SO-202605-002', customer: '李娜', amount: 599, status: 'pending' },
648
+ { key: '3', order: 'SO-202605-003', customer: '王芳', amount: 8800, status: 'paid' },
649
+ { key: '4', order: 'SO-202605-004', customer: '陈晨', amount: 320, status: 'refunded' },
650
+ ]
651
+
652
+ const statusMeta: Record<
653
+ OrderRecord['status'],
654
+ { label: string; color: 'success' | 'warning' | 'error' }
655
+ > = {
656
+ paid: { label: '已支付', color: 'success' },
657
+ pending: { label: '待支付', color: 'warning' },
658
+ refunded: { label: '已退款', color: 'error' },
659
+ }
660
+
661
+ const columns: TableColumn<OrderRecord>[] = [
662
+ { key: 'order', title: '订单号' },
663
+ { key: 'customer', title: '客户' },
664
+ {
665
+ key: 'amount',
666
+ title: '金额',
667
+ align: 'right',
668
+ render: (value) => `¥ ${(value as number).toLocaleString('zh-CN')}`,
669
+ },
670
+ {
671
+ key: 'status',
672
+ title: '状态',
673
+ render: (value) => {
674
+ const meta = statusMeta[value as OrderRecord['status']]
675
+ return <Tag color={meta.color}>{meta.label}</Tag>
676
+ },
677
+ },
678
+ {
679
+ key: 'action',
680
+ title: '操作',
681
+ align: 'right',
682
+ render: (_value, record) => <Button type="link">查看 {record.order}</Button>,
683
+ },
684
+ ]
685
+
686
+ export default () => <Table columns={columns} data={data} />
687
+ ```
688
+
689
+ ### 自定义渲染 (multiple-tags)
690
+
691
+ 单元格内可放置多个 `Tag`。表格单元格统一通过 `--table-padding-y` 提供上下间距,自定义 `render` 容器无需重复补 padding;多个 Tag 之间使用 `gap` 控制间距。Tag 默认 `max-width` 为 180,长文案会单行省略,hover 可查看完整内容。
692
+
693
+ ```tsx
694
+ import type { TableColumn } from '@apexhub/apex-ui-react'
695
+
696
+ import { Table, Tag } from '@apexhub/apex-ui-react'
697
+
698
+ type ProductRecord = {
699
+ key: string
700
+ name: string
701
+ tags: Array<{ label: string; color: 'brand' | 'success' | 'warning' | 'error' | 'default' }>
702
+ }
703
+
704
+ const LONG_TAG_LABELS = {
705
+ priority: '高优先级紧急处理事项:需在本周内完成跨部门评审并同步相关方确认结果',
706
+ region: '华东大区(含上海、杭州、南京、苏州、无锡及周边城市)重点客户专项运营',
707
+ category: '企业级数据中台与智能分析平台解决方案 / 含实时数仓与权限治理模块',
708
+ } as const
709
+
710
+ const data: ProductRecord[] = [
711
+ {
712
+ key: '1',
713
+ name: '洞察分析平台',
714
+ tags: [
715
+ { label: LONG_TAG_LABELS.priority, color: 'error' },
716
+ { label: LONG_TAG_LABELS.region, color: 'brand' },
717
+ { label: LONG_TAG_LABELS.category, color: 'success' },
718
+ ],
719
+ },
720
+ {
721
+ key: '2',
722
+ name: '客户成功工作台',
723
+ tags: [
724
+ { label: LONG_TAG_LABELS.region, color: 'brand' },
725
+ { label: '季度复盘待办:整理本月续约风险清单并同步客户成功经理', color: 'warning' },
726
+ { label: LONG_TAG_LABELS.category, color: 'default' },
727
+ ],
728
+ },
729
+ {
730
+ key: '3',
731
+ name: '权限治理中心',
732
+ tags: [
733
+ { label: LONG_TAG_LABELS.priority, color: 'error' },
734
+ { label: '安全合规专项:完成敏感字段脱敏策略评审与灰度发布计划', color: 'warning' },
735
+ ],
736
+ },
737
+ ]
738
+
739
+ const columns: TableColumn<ProductRecord>[] = [
740
+ { key: 'name', title: '产品', width: 140 },
741
+ {
742
+ key: 'tags',
743
+ title: '标签',
744
+ render: (_value, record) => (
745
+ <div
746
+ style={{
747
+ display: 'flex',
748
+ flexWrap: 'wrap',
749
+ gap: 8,
750
+ alignItems: 'center',
751
+ }}
752
+ >
753
+ {record.tags.map((tag) => (
754
+ <Tag key={tag.label} color={tag.color}>
755
+ {tag.label}
756
+ </Tag>
757
+ ))}
758
+ </div>
759
+ ),
760
+ },
761
+ ]
762
+
763
+ export default () => <Table columns={columns} data={data} pagination={false} />
764
+ ```
765
+
766
+ ### 自定义渲染 (max-tag-count)
767
+
768
+ 固定列宽场景下可配置最多展示个数(如下例 `maxTagCount = 2`):Tag 竖排,超出部分在末行右侧以 `+N` 折叠;hover `+N` 弹出全部 Tag。
769
+
770
+ ```tsx
771
+ import type { TableColumn } from '@apexhub/apex-ui-react'
772
+
773
+ import { Popover, Table, Tag } from '@apexhub/apex-ui-react'
774
+
775
+ type ToolRecord = {
776
+ key: string
777
+ name: string
778
+ tools: string[]
779
+ }
780
+
781
+ const MAX_TAG_COUNT = 2
782
+
783
+ const data: ToolRecord[] = [
784
+ {
785
+ key: '1',
786
+ name: '张伟',
787
+ tools: [
788
+ 'Adobe Illustrator (熟练掌握)',
789
+ 'ChatGPT (熟练掌握,可独立完成复杂提示词工程)',
790
+ 'Figma (熟练掌握)',
791
+ ],
792
+ },
793
+ {
794
+ key: '2',
795
+ name: '李娜',
796
+ tools: ['Adobe Firefly (熟练掌握,含生成式填充与扩展工作流)'],
797
+ },
798
+ {
799
+ key: '3',
800
+ name: '王芳',
801
+ tools: [
802
+ 'Adobe After Effects (熟练掌握)',
803
+ 'Adobe Firefly (熟练掌握)',
804
+ 'Premiere Pro (熟练掌握)',
805
+ 'DaVinci Resolve (熟练掌握)',
806
+ 'Blender (一般掌握)',
807
+ 'Cinema 4D (一般掌握)',
808
+ 'Midjourney (熟练掌握)',
809
+ 'Runway (一般掌握)',
810
+ ],
811
+ },
812
+ {
813
+ key: '4',
814
+ name: '陈晨',
815
+ tools: ['Adobe Photoshop'],
816
+ },
817
+ {
818
+ key: '5',
819
+ name: '赵敏',
820
+ tools: ['Adobe Illustrator (熟练掌握,含品牌视觉与图标体系)'],
821
+ },
822
+ ]
823
+
824
+ function AllToolsPopoverContent({ tools }: { tools: string[] }) {
825
+ return (
826
+ <div
827
+ style={{
828
+ display: 'flex',
829
+ flexWrap: 'wrap',
830
+ gap: 8,
831
+ maxWidth: 320,
832
+ maxHeight: 256,
833
+ overflow: 'auto',
834
+ }}
835
+ >
836
+ {tools.map((label) => (
837
+ <Tag key={label} variant="outlined">
838
+ {label}
839
+ </Tag>
840
+ ))}
841
+ </div>
842
+ )
843
+ }
844
+
845
+ function ToolExperienceTags({ tools }: { tools: string[] }) {
846
+ const visible = tools.slice(0, MAX_TAG_COUNT)
847
+ const overflowCount = tools.length - visible.length
848
+ const showOverflow = overflowCount > 0
849
+
850
+ return (
851
+ <div
852
+ style={{
853
+ display: 'flex',
854
+ flexDirection: 'column',
855
+ gap: 8,
856
+ width: '100%',
857
+ minWidth: 0,
858
+ // 让 Tag 跟随列宽截断,而不是锁定默认 180
859
+ ['--tag-width-max' as string]: '100%',
860
+ }}
861
+ >
862
+ {visible.map((label, index) => {
863
+ const isLast = index === visible.length - 1
864
+ if (!(isLast && showOverflow)) {
865
+ return (
866
+ <Tag key={label} variant="outlined" style={{ width: '100%', minWidth: 0 }}>
867
+ {label}
868
+ </Tag>
869
+ )
870
+ }
871
+
872
+ return (
873
+ <div
874
+ key={label}
875
+ style={{
876
+ display: 'flex',
877
+ alignItems: 'center',
878
+ gap: 8,
879
+ width: '100%',
880
+ minWidth: 0,
881
+ }}
882
+ >
883
+ <Tag variant="outlined" style={{ flex: '1 1 auto', minWidth: 0 }}>
884
+ {label}
885
+ </Tag>
886
+ <Popover
887
+ trigger="hover"
888
+ placement="top"
889
+ content={<AllToolsPopoverContent tools={tools} />}
890
+ >
891
+ <Tag variant="outlined" style={{ flexShrink: 0 }}>
892
+ +{overflowCount}
893
+ </Tag>
894
+ </Popover>
895
+ </div>
896
+ )
897
+ })}
898
+ </div>
899
+ )
900
+ }
901
+
902
+ const columns: TableColumn<ToolRecord>[] = [
903
+ { key: 'name', title: '姓名', width: 100 },
904
+ {
905
+ key: 'tools',
906
+ title: '工具经验',
907
+ width: 220,
908
+ render: (_value, record) => <ToolExperienceTags tools={record.tools} />,
909
+ },
910
+ ]
911
+
912
+ export default () => <Table columns={columns} data={data} pagination={false} />
913
+ ```
914
+
915
+ ### 行展开
916
+
917
+ 通过 `expandable.expandedRowRender` 在行下方渲染展开面板;数据含嵌套 子内容 字段时自动切换为树形模式。
918
+
919
+ ```tsx
920
+ import { Table } from '@apexhub/apex-ui-react'
921
+
922
+ const columns = [
923
+ { key: 'name', title: '姓名' },
924
+ { key: 'address', title: '地址' },
925
+ ]
926
+
927
+ const data = [
928
+ { key: '1', name: '张伟', address: '北京市朝阳区', description: '北京市朝阳区建国路 88 号' },
929
+ {
930
+ key: '2',
931
+ name: '李娜',
932
+ address: '上海市浦东新区',
933
+ description: '上海市浦东新区世纪大道 100 号',
934
+ },
935
+ { key: '3', name: '王芳', address: '广州市天河区', description: '广州市天河区体育西路 66 号' },
936
+ ]
937
+
938
+ export default () => (
939
+ <Table
940
+ columns={columns}
941
+ data={data}
942
+ expandable={{
943
+ expandedRowRender: (record) => <div>详细信息:{record.description}</div>,
944
+ }}
945
+ />
946
+ )
947
+ ```
948
+
949
+ ### 虚拟滚动
950
+
951
+ 大数据量时开启 `virtual`,需配合 `scroll.y` 或 `flexHeight` 提供受限高度;无受限高度时自动降级。
952
+
953
+ ```tsx
954
+ import { Table } from '@apexhub/apex-ui-react'
955
+
956
+ const columns = [
957
+ { key: 'name', title: '姓名', width: 120 },
958
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
959
+ { key: 'address', title: '地址' },
960
+ ]
961
+
962
+ const data = Array.from({ length: 200 }, (_, index) => ({
963
+ key: String(index + 1),
964
+ name: `用户 ${String(index + 1).padStart(3, '0')}`,
965
+ age: 18 + (index % 50),
966
+ address: `城市 ${(index % 10) + 1} 区`,
967
+ }))
968
+
969
+ export default () => (
970
+ <Table
971
+ columns={columns}
972
+ data={data}
973
+ size="small"
974
+ pagination={false}
975
+ scroll={{ y: 320 }}
976
+ virtual
977
+ />
978
+ )
979
+ ```
980
+
981
+ ### 总结栏
982
+
983
+ 通过 `summary` 渲染 `Table.Summary` 复合组件,在表尾展示合计行。
984
+
985
+ ```tsx
986
+ import { Table } from '@apexhub/apex-ui-react'
987
+
988
+ const columns = [
989
+ { key: 'name', title: '姓名' },
990
+ { key: 'age', title: '年龄', align: 'right' as const, width: 80 },
991
+ { key: 'address', title: '地址' },
992
+ ]
993
+
994
+ const data = [
995
+ { key: '1', name: '张伟', age: 32, address: '北京市朝阳区' },
996
+ { key: '2', name: '李娜', age: 28, address: '上海市浦东新区' },
997
+ { key: '3', name: '王芳', age: 45, address: '广州市天河区' },
998
+ ]
999
+
1000
+ export default () => (
1001
+ <Table
1002
+ columns={columns}
1003
+ data={data}
1004
+ pagination={false}
1005
+ summary={(currentData) => {
1006
+ const totalAge = currentData.reduce((sum, row) => sum + row.age, 0)
1007
+ return (
1008
+ <Table.Summary>
1009
+ <Table.Summary.Row>
1010
+ <Table.Summary.Cell index={0}>合计</Table.Summary.Cell>
1011
+ <Table.Summary.Cell index={1} align="right">
1012
+ {totalAge}
1013
+ </Table.Summary.Cell>
1014
+ <Table.Summary.Cell index={2}>共 {currentData.length} 人</Table.Summary.Cell>
1015
+ </Table.Summary.Row>
1016
+ </Table.Summary>
1017
+ )
1018
+ }}
1019
+ />
1020
+ )
1021
+ ```
1022
+
1023
+ ## DOM 结构
1024
+
1025
+ 源码声明的静态 `data-slot`:`table-element`、`table-scroll-shell`、`table-scroll`、`table-empty-fixed`、`table-summary-wrap`、`table-element-summary`、`table-container`、`table`、`table-header-wrap`、`table-element-header`、`table-expand-trigger`、`table-selection-cell`、`table-selection-index`、`table-selection-all`、`table-selection-radio`、`table-selection-checkbox`、`table-virtual-spacer`、`table-expanded-row`、`table-expanded-cell`、`table-tbody`、`table-cell-head`、`table-cell`、`table-col`、`table-row-empty`、`table-cell-empty`、`table-empty-image`、`table-thead`、`table-row`、`table-pagination`、`table-scrollbar`、`table-scrollbar-track-y`、`table-scrollbar-thumb-y`、`table-scrollbar-track-x`、`table-scrollbar-thumb-x`、`table-skeleton-row`、`table-skeleton-cell`、`table-summary`、`table-summary-row`、`table-summary-cell`。具体节点随模式和状态出现,不表示固定嵌套顺序。
1026
+
1027
+ ## 样式定制
1028
+
1029
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
1030
+
1031
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
1032
+
1033
+ ## FAQ
1034
+
1035
+ ### 为什么设置了 `ellipsis` 但没有 Tooltip?
1036
+
1037
+ `ellipsis.tooltip` 仅对**纯文本**(`string` / `number`)列生效;若 `render` 返回自定义 ReactNode,列会改为弹性行高而不截断。Tooltip 也仅在内容**实际溢出**时弹出。
1038
+
1039
+
1040
+ ### `emptyText` 和 ApexProvider 的 locale 谁优先?
1041
+
1042
+ 单表 `emptyText` prop 优先于 `ApexProvider` 的 `locale.Table.emptyText`,再其次才是内置默认文案。
1043
+
1044
+ ### 列显隐会隐藏选择列吗?
1045
+
1046
+ 不会。`hiddenColumnKeys` 仅作用于数据列;行选择列、展开列等 prefix 列始终保留。