@canvas-components/list-table 0.3.13 → 0.3.15
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.
- package/README.md +317 -272
- package/dist/index.cjs +4540 -4347
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +14 -3
- package/dist/index.d.ts +14 -3
- package/dist/index.js +4541 -4349
- package/dist/index.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,272 +1,317 @@
|
|
|
1
|
-
# @canvas-components/list-table
|
|
2
|
-
|
|
3
|
-
`@canvas-components/list-table` 是整个项目的纯原生 Canvas 表格核心包，不依赖 React，可直接在 DOM 容器中创建高性能表格实例，也可作为适配层的底层引擎使用。
|
|
4
|
-
|
|
5
|
-
## 功能作用
|
|
6
|
-
|
|
7
|
-
- 原生 Canvas 表格渲染
|
|
8
|
-
- 大数据量虚拟滚动
|
|
9
|
-
- 多级表头、固定列、汇总行
|
|
10
|
-
- 排序、过滤、自动合并单元格
|
|
11
|
-
- 行选择、展开树表、右键菜单
|
|
12
|
-
- 单元格编辑、校验、tooltip、图片预览
|
|
13
|
-
- 列宽调整、列拖拽、行拖拽、轮播滚动
|
|
14
|
-
- 内建二维码、条形码、进度、图表、评分、按钮等单元格内容
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
`
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
`
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
- `
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
1
|
+
# @canvas-components/list-table
|
|
2
|
+
|
|
3
|
+
`@canvas-components/list-table` 是整个项目的纯原生 Canvas 表格核心包，不依赖 React，可直接在 DOM 容器中创建高性能表格实例，也可作为适配层的底层引擎使用。
|
|
4
|
+
|
|
5
|
+
## 功能作用
|
|
6
|
+
|
|
7
|
+
- 原生 Canvas 表格渲染
|
|
8
|
+
- 大数据量虚拟滚动
|
|
9
|
+
- 多级表头、固定列、汇总行
|
|
10
|
+
- 排序、过滤、自动合并单元格
|
|
11
|
+
- 行选择、展开树表、右键菜单
|
|
12
|
+
- 单元格编辑、校验、tooltip、图片预览
|
|
13
|
+
- 列宽调整、列拖拽、行拖拽、轮播滚动
|
|
14
|
+
- 内建二维码、条形码、进度、图表、评分、按钮等单元格内容
|
|
15
|
+
|
|
16
|
+
### 展开详情自动高度
|
|
17
|
+
|
|
18
|
+
`expandable.expandedRowRender` 返回标签、文本等富内容时，不传 `expandedRowHeight` 即按实际内容宽度自动换行、测高。容器宽度、列宽、字体或密度变化后会重新计算，并同步更新行位置和滚动范围。测量与绘制共用布局规则，业务侧无需自行测量标签或监听容器宽度。
|
|
19
|
+
|
|
20
|
+
显式设置 `expandedRowHeight` 数字或回调时仍优先使用该配置；嵌套子表继续使用其独立的内容高度计算。
|
|
21
|
+
|
|
22
|
+
### 分页尺寸缓存
|
|
23
|
+
|
|
24
|
+
设置表格 `storageKey` 后，用户切换每页条数会自动保存到 localStorage，下次创建表格时恢复。不同表格应使用不同的键；不缓存页码，不影响滚动加载。无键、缓存无效或浏览器禁用存储时，继续使用默认配置。
|
|
25
|
+
|
|
26
|
+
显式传入 `pagination.pageSize` 时以受控值为准。外部负责请求的封装（如 WWISuperTable）应在首次请求前读取缓存，初始化自己的分页状态，避免只改变显示值而请求条数不一致：
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { getListTableStoredPageSize } from '@canvas-components/list-table';
|
|
30
|
+
|
|
31
|
+
const initialPageSize = explicitPageSize ?? getListTableStoredPageSize(storageKey) ?? 10;
|
|
32
|
+
// 将 initialPageSize 用于首次请求和受控 pagination.pageSize。
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
该读取方法也由 `@canvas-components/react-list-table` 导出。
|
|
36
|
+
|
|
37
|
+
## 安装方法
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pnpm add @canvas-components/list-table
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
最低环境要求：
|
|
44
|
+
|
|
45
|
+
- `Node.js >= 18.12.0`
|
|
46
|
+
- `pnpm >= 9.0.0`
|
|
47
|
+
|
|
48
|
+
## 使用方法
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import { ListTable } from "@canvas-components/list-table";
|
|
52
|
+
|
|
53
|
+
const container = document.querySelector("#table") as HTMLElement;
|
|
54
|
+
|
|
55
|
+
const table = new ListTable(container, {
|
|
56
|
+
type: "list",
|
|
57
|
+
width: "100%",
|
|
58
|
+
height: 480,
|
|
59
|
+
rowKey: "id",
|
|
60
|
+
columns: [
|
|
61
|
+
{ key: "name", title: "姓名", dataIndex: "name", width: 180 },
|
|
62
|
+
{ key: "age", title: "年龄", dataIndex: "age", width: 120, align: "right" },
|
|
63
|
+
],
|
|
64
|
+
dataSource: [
|
|
65
|
+
{ id: 1, name: "张三", age: 28 },
|
|
66
|
+
{ id: 2, name: "李四", age: 31 },
|
|
67
|
+
],
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
table.mount();
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## 属性说明
|
|
74
|
+
|
|
75
|
+
### 实例配置 `ListTableOptions`
|
|
76
|
+
|
|
77
|
+
| 属性 | 类型 | 说明 |
|
|
78
|
+
| ------------------ | -------------------------------------------------------------------------------------- | -------------------------------- |
|
|
79
|
+
| `type` | `"list"` | 表格类型，当前稳定支持列表表格 |
|
|
80
|
+
| `rowKey` | `string \| number \| Array<string \| number> \| ((record, index) => string \| number)` | 行主键解析规则 |
|
|
81
|
+
| `columns` | `ListTableColumn[]` | 列配置集合 |
|
|
82
|
+
| `width` | `number \| string` | 表格宽度 |
|
|
83
|
+
| `height` | `number \| string` | 表格高度 |
|
|
84
|
+
| `dataSource` | `RecordType[]` | 表格数据源 |
|
|
85
|
+
| `emptyText` | `string` | 空状态文案 |
|
|
86
|
+
| `theme` | `Partial<ListTableTheme>` | 主题覆盖 |
|
|
87
|
+
| `striped` | `boolean` | 是否开启斑马纹 |
|
|
88
|
+
| `highlightMode` | `"cell" \| "row" \| "column" \| "cross"` | 点击高亮模式 |
|
|
89
|
+
| `contextMenu` | `false \| ListTableContextMenuOptions` | 右键菜单配置 |
|
|
90
|
+
| `grouping` | `ListTableGroupingOptions` | 分组栏、初始分组列与变化回调 |
|
|
91
|
+
| `rowHeight` | `number \| "auto"` | 行高 |
|
|
92
|
+
| `headerRowHeight` | `number` | 表头单行高度 |
|
|
93
|
+
| `summaryRowHeight` | `number` | 汇总行高度 |
|
|
94
|
+
| `overscanRowCount` | `number` | 虚拟滚动预渲染行数 |
|
|
95
|
+
| `query` | `ListTableQueryOptions` | 排序、过滤、合并单元格配置 |
|
|
96
|
+
| `rowSelector` | `boolean \| ListTableRowSelectorOptions` | 最左侧空白整行选择器配置 |
|
|
97
|
+
| `rowSelection` | `ListTableRowSelectionOptions` | 行选择配置 |
|
|
98
|
+
| `expandable` | `ListTableExpandableOptions` | 树表 / 展开行配置 |
|
|
99
|
+
| `pagination` | `false \| ListTablePaginationOptions` | 分页或滚动加载配置 |
|
|
100
|
+
| `scrollbar` | `ListTableScrollbarOptions` | 滚动条配置 |
|
|
101
|
+
| `carouselScroll` | `ListTableCarouselScrollOptions` | 自动轮播滚动配置 |
|
|
102
|
+
| `stretchColumns` | `boolean` | 列总宽不足时是否拉伸补齐 |
|
|
103
|
+
| `resizable` | `boolean` | 是否开启列宽拖拽 |
|
|
104
|
+
| `storageKey` | `string` | 列配置、查询、缩放和密度持久化键 |
|
|
105
|
+
| `draggable` | `boolean` | 是否开启列拖拽排序 |
|
|
106
|
+
| `tableId` | `string` | 表格唯一标识 |
|
|
107
|
+
| `rowDrag` | `ListTableRowDragOptions` | 行拖拽配置 |
|
|
108
|
+
| `debug` | `ListTableDebugOptions` | 调试配置 |
|
|
109
|
+
|
|
110
|
+
### 分批加载与服务端汇总
|
|
111
|
+
|
|
112
|
+
数据仍在异步生成或分批加载时，设置表格顶层属性 `loading: true`。此时汇总行及标题正常显示，统计结果保持空白，也不会计算首批临时数据。完整数据就绪后，将完整 `dataSource` 与 `loading: false` 一起更新，表格自动计算汇总并在完成后统一显示结果。默认值为 `false`，正常的空数据仍可汇总为零。
|
|
113
|
+
|
|
114
|
+
使用服务端汇总时，通过 `query.summaryValues` 传入以列 `key` 为键的对象或 Map。若数据和汇总分别请求，可保持 `loading: true`，待两者都返回后再设为 `false`；此配置同样支持 React 适配包，外部无需控制汇总计算状态。
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
const options = {
|
|
118
|
+
dataSource: rows,
|
|
119
|
+
loading,
|
|
120
|
+
query: {
|
|
121
|
+
// 服务端汇总可选；不传则使用本地异步汇总。
|
|
122
|
+
summaryValues: serverSummaryValues,
|
|
123
|
+
},
|
|
124
|
+
};
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### 列配置 `ListTableColumn`
|
|
128
|
+
|
|
129
|
+
| 属性 | 类型 | 说明 |
|
|
130
|
+
| --------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
|
|
131
|
+
| `key` | `string` | 列唯一标识 |
|
|
132
|
+
| `title` | `string` | 列标题 |
|
|
133
|
+
| `dataIndex` | `string \| number \| Array<string \| number>` | 取值路径 |
|
|
134
|
+
| `children` | `ListTableColumn[]` | 子列，用于多级表头 |
|
|
135
|
+
| `width` | `number` | 列宽 |
|
|
136
|
+
| `minWidth` / `maxWidth` | `number` | 允许调整的最小 / 最大列宽 |
|
|
137
|
+
| `align` | `"left" \| "center" \| "right"` | 内容对齐 |
|
|
138
|
+
| `headerAlign` | `"left" \| "center" \| "right"` | 表头水平对齐，未传时回退到 `align` |
|
|
139
|
+
| `fixed` | `"left" \| "right"` | 固定列 |
|
|
140
|
+
| `hidden` | `boolean` | 是否隐藏 |
|
|
141
|
+
| `ellipsis` | `boolean` | 超出是否省略 |
|
|
142
|
+
| `editable` | `boolean \| (text, record, index) => boolean` | 是否允许编辑 |
|
|
143
|
+
| `formItemProps` | `ListTableFormItemPropsConfig` | 编辑器配置 |
|
|
144
|
+
| `resizable` | `boolean` | 单列是否允许调整宽度 |
|
|
145
|
+
| `draggable` | `boolean` | 单列是否允许拖拽 |
|
|
146
|
+
| `allowSort` | `boolean` | 是否开启排序 |
|
|
147
|
+
| `allowFilter` | `boolean` | 是否开启过滤 |
|
|
148
|
+
| `filterOptions` | `ListTableFilterOption[]` | 精确过滤选项 |
|
|
149
|
+
| `cellType` | `ListTableCellContent["type"]` | 内建单元格类型 |
|
|
150
|
+
| `moneyFormat` | `ListTableMoneyFormatOptions` | 金额格式配置，仅在 `cellType: "money"` 时生效 |
|
|
151
|
+
| `dataFormat` | `"default" \| "text" \| "number" \| "thousands" \| "decimal" \| ...` | 右键菜单设置的数据展示格式 |
|
|
152
|
+
| `cellStyle.verticalAlign` | `"top" \| "middle" \| "bottom"` | 表体垂直对齐 |
|
|
153
|
+
| `headerStyle.verticalAlign` | `"top" \| "middle" \| "bottom"` | 表头垂直对齐 |
|
|
154
|
+
| `render` | `(value, record, rowIndex, column) => ...` | 自定义渲染 |
|
|
155
|
+
| `onCell` | `(value, record, rowIndex, column) => { rowSpan?: number; colSpan?: number }` | 单元格跨度控制 |
|
|
156
|
+
| `summary` | `boolean \| ListTableSummaryConfig` | 汇总配置 |
|
|
157
|
+
| `summaryTitle` | `string` | 汇总标题文本 |
|
|
158
|
+
|
|
159
|
+
### 常见嵌套能力
|
|
160
|
+
|
|
161
|
+
| 配置 | 说明 |
|
|
162
|
+
| -------------- | ---------------------------------------------------------------------------- |
|
|
163
|
+
| `query` | 排序、筛选、远程查询、自动合并单元格 |
|
|
164
|
+
| `rowSelector` | 空白整行选择器，单击选中一行、纵向拖拽选中连续多行 |
|
|
165
|
+
| `rowSelection` | checkbox / radio 行选择 |
|
|
166
|
+
| `expandable` | 树形数据、详情展开、展开列 |
|
|
167
|
+
| `pagination` | 按钮分页或滚动加载 |
|
|
168
|
+
| `rowDrag` | 行拖拽、跨表拖拽、拖放回调 |
|
|
169
|
+
| `contextMenu` | 复制、导出、排序、冻结、列显示、分组栏、对齐、数据格式、密度、缩放等菜单能力 |
|
|
170
|
+
|
|
171
|
+
分组功能默认关闭，只有显式传入 `grouping: {}` 才会启用右键菜单中的分组入口。`grouping.visible` 控制 Canvas 顶部分组栏初始显隐，默认 `false`；`grouping.columnKeys` 按顺序声明初始分组层级。显示分组栏后可将列头拖入栏内；分组列会从表头和表体隐藏，仅以 Canvas 标签展示，移除标签会立即恢复该列。右键分组栏可隐藏分组栏；`grouping.onChange` 会在标签增删时收到最新列 key 列表。
|
|
172
|
+
|
|
173
|
+
`rowSelection.selectRowByClick` 控制点击普通表体区域时是否同步切换 checkbox / radio 选择状态，默认关闭。该配置直接复用表格内部选择状态，无需通过外部 `key` 强制重新创建表格；查看详情等业务点击仍使用 `onRow().onClick`。
|
|
174
|
+
|
|
175
|
+
`rowSelector` 与 `rowSelection` 相互独立。默认在最左侧展示宽度为 `12px` 的空白选择器列；传入 `{ width: 32 }` 可自定义宽度，传入 `false` 可隐藏。该列只建立 Canvas 整行选区，不修改 checkbox / radio 的选中数据。
|
|
176
|
+
|
|
177
|
+
## 方法说明
|
|
178
|
+
|
|
179
|
+
| 方法 | 签名 | 说明 |
|
|
180
|
+
| ------------------ | ------------------------------------------------ | ----------------------------------------------------- |
|
|
181
|
+
| `constructor` | `new ListTable(container, options)` | 创建实例 |
|
|
182
|
+
| `mount` | `() => void` | 挂载表格 |
|
|
183
|
+
| `updateOptions` | `(options) => void` | 更新配置并刷新 |
|
|
184
|
+
| `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
|
|
185
|
+
| `validate` | `() => Promise<RecordType[]>` | 手动触发校验，失败时抛出 `ListTableValidationFailure` |
|
|
186
|
+
| `exportXlsx` | `(options?: ListTableExportXlsxOptions) => void` | 异步导出全部原始数据为 XLSX，可配置文件名和汇总行 |
|
|
187
|
+
| `scrollTo` | `(options: ListTableScrollToOptions) => void` | 滚动到指定行 |
|
|
188
|
+
| `destroy` | `() => void` | 销毁实例 |
|
|
189
|
+
|
|
190
|
+
列配置可通过 `settingTitle`、`initialHide`、`hideInSetting`、`disableHide` 约束列设置中的标题、初始显隐和隐藏权限。
|
|
191
|
+
|
|
192
|
+
### XLSX Worker 导出
|
|
193
|
+
|
|
194
|
+
`exportXlsx()` 默认对 1 万行及以上数据尝试 Worker；现有调用无需修改。表格加载提示会显示已处理行数与文件生成阶段。取值和 `render` 回调仍在主线程执行，工作表构建、文件编码交给 Worker。
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
const controller = new AbortController();
|
|
198
|
+
table.exportXlsx({
|
|
199
|
+
fileName: "表格数据",
|
|
200
|
+
includeSummary: true,
|
|
201
|
+
worker: "auto", // true：始终尝试；false：使用主线程
|
|
202
|
+
maxRowsPerFile: 100_000, // 默认十万行；20 列以内无需降低每份行数
|
|
203
|
+
signal: controller.signal,
|
|
204
|
+
onError: (error) => console.error("导出失败", error), // 可替换为业务提示
|
|
205
|
+
onProgress: ({ phase, completedRows, totalRows }) => {
|
|
206
|
+
console.log(phase, completedRows, totalRows);
|
|
207
|
+
},
|
|
208
|
+
});
|
|
209
|
+
// 需要取消时调用 controller.abort()。
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
大数据按行数和单元格预算自动拆成多个独立 XLSX，文件名追加 `_001`、`_002`。每份保留表头，汇总只追加在全部数据末尾。逐份生成、下载并释放，不同时持有全部工作簿。进度包含 `fileIndex`、`fileCount`；可通过 `saveFile(blob, fileName, part)` 接管保存，等待其返回后才生成下一份。
|
|
213
|
+
|
|
214
|
+
浏览器可能要求允许下载多个文件。取消或失败会停止后续文件，已经下载的文件保留。每份默认最多 10 万行（含汇总尾行、不含表头），20 列以内按此行数分文件；超过 20 列时受 2,000,020 个单元格预算限制，适当减小每份行数。长文本另有 16M UTF-16 码元安全预算，超限时需调低 `maxRowsPerFile`。Worker 不可用时回退；CSV、TXT、JSON 不受影响。千万行多列数据仍建议服务端导出。
|
|
215
|
+
|
|
216
|
+
## 内建单元格内容
|
|
217
|
+
|
|
218
|
+
`render` 支持直接返回结构化内容，内建类型包括：
|
|
219
|
+
|
|
220
|
+
- `text`
|
|
221
|
+
- `money`
|
|
222
|
+
- `image`
|
|
223
|
+
- `qrcode`
|
|
224
|
+
- `barcode`
|
|
225
|
+
- `progress`
|
|
226
|
+
- `chart`
|
|
227
|
+
- `rate`
|
|
228
|
+
- `button`
|
|
229
|
+
- `tag`
|
|
230
|
+
- `color`
|
|
231
|
+
- `icon`
|
|
232
|
+
- `checkbox`
|
|
233
|
+
- `radio`
|
|
234
|
+
- `switch`
|
|
235
|
+
- `link`
|
|
236
|
+
|
|
237
|
+
`icon` 当前内置 `star`、`sun`、`moon`、`check`（√）和 `close`（×）。
|
|
238
|
+
|
|
239
|
+
### 金额单元格示例
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
const columns = [
|
|
243
|
+
{
|
|
244
|
+
title: "金额",
|
|
245
|
+
dataIndex: "amount",
|
|
246
|
+
width: 140,
|
|
247
|
+
align: "right",
|
|
248
|
+
cellType: "money",
|
|
249
|
+
moneyFormat: {
|
|
250
|
+
symbol: "¥",
|
|
251
|
+
thousandsSeparator: true,
|
|
252
|
+
decimalPlaces: 2,
|
|
253
|
+
},
|
|
254
|
+
},
|
|
255
|
+
{
|
|
256
|
+
title: "结算金额",
|
|
257
|
+
dataIndex: "settlementAmount",
|
|
258
|
+
width: 160,
|
|
259
|
+
align: "right",
|
|
260
|
+
render(value) {
|
|
261
|
+
return {
|
|
262
|
+
type: "money",
|
|
263
|
+
value: value as number,
|
|
264
|
+
symbol: "$",
|
|
265
|
+
thousandsSeparator: ",",
|
|
266
|
+
decimalPlaces: 1,
|
|
267
|
+
};
|
|
268
|
+
},
|
|
269
|
+
},
|
|
270
|
+
];
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## 行点击事件
|
|
274
|
+
|
|
275
|
+
`onRow` 使用 AntD Table 风格的回调结构。由于表格由 Canvas 渲染，目前只支持整行点击事件；行高亮继续由表格内置选区处理。
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
const table = new ListTable(container, {
|
|
279
|
+
columns,
|
|
280
|
+
dataSource,
|
|
281
|
+
onRow: (record, rowIndex) => ({
|
|
282
|
+
onClick: (event) => {
|
|
283
|
+
console.log(record, rowIndex, event);
|
|
284
|
+
},
|
|
285
|
+
}),
|
|
286
|
+
});
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
## 推荐搭配
|
|
290
|
+
|
|
291
|
+
- 原生 DOM 场景：直接使用 `ListTable`
|
|
292
|
+
- React 场景：优先使用 `@canvas-components/react-list-table`
|
|
293
|
+
- 二维码 / 条形码 / 图表单元格：配合 `@canvas-components/qrcode`、`@canvas-components/barcode`、`@canvas-components/chart`
|
|
294
|
+
|
|
295
|
+
## 滚动条配置
|
|
296
|
+
|
|
297
|
+
`scrollbar` 同时适用于原生表格与 React 适配组件。通用配置由 `horizontal`、`vertical` 单独覆盖；不配置时保留原有外观。
|
|
298
|
+
|
|
299
|
+
```ts
|
|
300
|
+
scrollbar: {
|
|
301
|
+
thickness: 10,
|
|
302
|
+
thumbColor: '#8793a5',
|
|
303
|
+
trackColor: '#f1f5f9',
|
|
304
|
+
buttonColor: '#475569',
|
|
305
|
+
thumbRadius: 4,
|
|
306
|
+
horizontal: { thickness: 8, thumbColor: '#1677ff' },
|
|
307
|
+
vertical: { thickness: 14, trackColor: '#e2e8f0' },
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
- `thickness`：横向滚动条高度、纵向滚动条宽度，单位 px，默认 10，最小 6。
|
|
312
|
+
- `thumbColor` / `trackColor` / `buttonColor`：滑块、滚动槽、两端箭头颜色。
|
|
313
|
+
- `thumbRadius`：滑块圆角，`0` 为直角；不传时保持胶囊形状。
|
|
314
|
+
- `horizontal: false` 或 `vertical: false`：单独隐藏某一轴，也可设置该轴的 `visible: false`。
|
|
315
|
+
- `visible: false`：同时隐藏两轴，优先于单轴设置。隐藏后释放对应槽位，仍可通过滚轮或程序滚动。
|
|
316
|
+
|
|
317
|
+
配置仅作用于当前 Canvas 表格，不修改全局浏览器滚动条样式。
|