@canvas-components/list-table 0.2.3 → 0.2.4
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 +229 -222
- package/dist/index.cjs +6324 -2014
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +154 -10
- package/dist/index.d.ts +154 -10
- package/dist/index.js +6325 -2015
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,222 +1,229 @@
|
|
|
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
|
-
```bash
|
|
19
|
-
pnpm add @canvas-components/list-table
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
最低环境要求：
|
|
23
|
-
|
|
24
|
-
- `Node.js >= 18.12.0`
|
|
25
|
-
- `pnpm >= 9.0.0`
|
|
26
|
-
|
|
27
|
-
## 使用方法
|
|
28
|
-
|
|
29
|
-
```ts
|
|
30
|
-
import { ListTable } from "@canvas-components/list-table";
|
|
31
|
-
|
|
32
|
-
const container = document.querySelector("#table") as HTMLElement;
|
|
33
|
-
|
|
34
|
-
const table = new ListTable(container, {
|
|
35
|
-
type: "list",
|
|
36
|
-
width: "100%",
|
|
37
|
-
height: 480,
|
|
38
|
-
rowKey: "id",
|
|
39
|
-
columns: [
|
|
40
|
-
{ key: "name", title: "姓名", dataIndex: "name", width: 180 },
|
|
41
|
-
{ key: "age", title: "年龄", dataIndex: "age", width: 120, align: "right" },
|
|
42
|
-
],
|
|
43
|
-
dataSource: [
|
|
44
|
-
{ id: 1, name: "张三", age: 28 },
|
|
45
|
-
{ id: 2, name: "李四", age: 31 },
|
|
46
|
-
],
|
|
47
|
-
});
|
|
48
|
-
|
|
49
|
-
table.mount();
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## 属性说明
|
|
53
|
-
|
|
54
|
-
### 实例配置 `ListTableOptions`
|
|
55
|
-
|
|
56
|
-
| 属性 | 类型 | 说明 |
|
|
57
|
-
| ------------------ | -------------------------------------------------------------------------------------- | ------------------------------ |
|
|
58
|
-
| `type` | `"list"` | 表格类型，当前稳定支持列表表格 |
|
|
59
|
-
| `rowKey` | `string \| number \| Array<string \| number> \| ((record, index) => string \| number)` | 行主键解析规则 |
|
|
60
|
-
| `columns` | `ListTableColumn[]` | 列配置集合 |
|
|
61
|
-
| `width` | `number \| string` | 表格宽度 |
|
|
62
|
-
| `height` | `number \| string` | 表格高度 |
|
|
63
|
-
| `dataSource` | `RecordType[]` | 表格数据源 |
|
|
64
|
-
| `emptyText` | `string` | 空状态文案 |
|
|
65
|
-
| `theme` | `Partial<ListTableTheme>` | 主题覆盖 |
|
|
66
|
-
| `striped` | `boolean` | 是否开启斑马纹 |
|
|
67
|
-
| `highlightMode` | `"cell" \| "row" \| "column" \| "cross"` | 点击高亮模式 |
|
|
68
|
-
| `contextMenu` | `false \| ListTableContextMenuOptions` | 右键菜单配置 |
|
|
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
|
-
|
|
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
|
+
```bash
|
|
19
|
+
pnpm add @canvas-components/list-table
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
最低环境要求：
|
|
23
|
+
|
|
24
|
+
- `Node.js >= 18.12.0`
|
|
25
|
+
- `pnpm >= 9.0.0`
|
|
26
|
+
|
|
27
|
+
## 使用方法
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { ListTable } from "@canvas-components/list-table";
|
|
31
|
+
|
|
32
|
+
const container = document.querySelector("#table") as HTMLElement;
|
|
33
|
+
|
|
34
|
+
const table = new ListTable(container, {
|
|
35
|
+
type: "list",
|
|
36
|
+
width: "100%",
|
|
37
|
+
height: 480,
|
|
38
|
+
rowKey: "id",
|
|
39
|
+
columns: [
|
|
40
|
+
{ key: "name", title: "姓名", dataIndex: "name", width: 180 },
|
|
41
|
+
{ key: "age", title: "年龄", dataIndex: "age", width: 120, align: "right" },
|
|
42
|
+
],
|
|
43
|
+
dataSource: [
|
|
44
|
+
{ id: 1, name: "张三", age: 28 },
|
|
45
|
+
{ id: 2, name: "李四", age: 31 },
|
|
46
|
+
],
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
table.mount();
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 属性说明
|
|
53
|
+
|
|
54
|
+
### 实例配置 `ListTableOptions`
|
|
55
|
+
|
|
56
|
+
| 属性 | 类型 | 说明 |
|
|
57
|
+
| ------------------ | -------------------------------------------------------------------------------------- | ------------------------------ |
|
|
58
|
+
| `type` | `"list"` | 表格类型，当前稳定支持列表表格 |
|
|
59
|
+
| `rowKey` | `string \| number \| Array<string \| number> \| ((record, index) => string \| number)` | 行主键解析规则 |
|
|
60
|
+
| `columns` | `ListTableColumn[]` | 列配置集合 |
|
|
61
|
+
| `width` | `number \| string` | 表格宽度 |
|
|
62
|
+
| `height` | `number \| string` | 表格高度 |
|
|
63
|
+
| `dataSource` | `RecordType[]` | 表格数据源 |
|
|
64
|
+
| `emptyText` | `string` | 空状态文案 |
|
|
65
|
+
| `theme` | `Partial<ListTableTheme>` | 主题覆盖 |
|
|
66
|
+
| `striped` | `boolean` | 是否开启斑马纹 |
|
|
67
|
+
| `highlightMode` | `"cell" \| "row" \| "column" \| "cross"` | 点击高亮模式 |
|
|
68
|
+
| `contextMenu` | `false \| ListTableContextMenuOptions` | 右键菜单配置 |
|
|
69
|
+
| `grouping` | `ListTableGroupingOptions` | 分组栏、初始分组列与变化回调 |
|
|
70
|
+
| `rowHeight` | `number \| "auto"` | 行高 |
|
|
71
|
+
| `headerRowHeight` | `number` | 表头单行高度 |
|
|
72
|
+
| `summaryRowHeight` | `number` | 汇总行高度 |
|
|
73
|
+
| `overscanRowCount` | `number` | 虚拟滚动预渲染行数 |
|
|
74
|
+
| `query` | `ListTableQueryOptions` | 排序、过滤、合并单元格配置 |
|
|
75
|
+
| `rowSelector` | `boolean \| ListTableRowSelectorOptions` | 最左侧空白整行选择器配置 |
|
|
76
|
+
| `rowSelection` | `ListTableRowSelectionOptions` | 行选择配置 |
|
|
77
|
+
| `expandable` | `ListTableExpandableOptions` | 树表 / 展开行配置 |
|
|
78
|
+
| `pagination` | `false \| ListTablePaginationOptions` | 分页或滚动加载配置 |
|
|
79
|
+
| `scrollbar` | `ListTableScrollbarOptions` | 滚动条配置 |
|
|
80
|
+
| `carouselScroll` | `ListTableCarouselScrollOptions` | 自动轮播滚动配置 |
|
|
81
|
+
| `stretchColumns` | `boolean` | 列总宽不足时是否拉伸补齐 |
|
|
82
|
+
| `resizable` | `boolean` | 是否开启列宽拖拽 |
|
|
83
|
+
| `storageKey` | `string` | 持久化键 |
|
|
84
|
+
| `draggable` | `boolean` | 是否开启列拖拽排序 |
|
|
85
|
+
| `tableId` | `string` | 表格唯一标识 |
|
|
86
|
+
| `rowDrag` | `ListTableRowDragOptions` | 行拖拽配置 |
|
|
87
|
+
| `debug` | `ListTableDebugOptions` | 调试配置 |
|
|
88
|
+
|
|
89
|
+
### 列配置 `ListTableColumn`
|
|
90
|
+
|
|
91
|
+
| 属性 | 类型 | 说明 |
|
|
92
|
+
| --------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
|
|
93
|
+
| `key` | `string` | 列唯一标识 |
|
|
94
|
+
| `title` | `string` | 列标题 |
|
|
95
|
+
| `dataIndex` | `string \| number \| Array<string \| number>` | 取值路径 |
|
|
96
|
+
| `children` | `ListTableColumn[]` | 子列，用于多级表头 |
|
|
97
|
+
| `width` | `number` | 列宽 |
|
|
98
|
+
| `minWidth` / `maxWidth` | `number` | 允许调整的最小 / 最大列宽 |
|
|
99
|
+
| `align` | `"left" \| "center" \| "right"` | 内容对齐 |
|
|
100
|
+
| `headerAlign` | `"left" \| "center" \| "right"` | 表头水平对齐，未传时回退到 `align` |
|
|
101
|
+
| `fixed` | `"left" \| "right"` | 固定列 |
|
|
102
|
+
| `hidden` | `boolean` | 是否隐藏 |
|
|
103
|
+
| `ellipsis` | `boolean` | 超出是否省略 |
|
|
104
|
+
| `editable` | `boolean \| (text, record, index) => boolean` | 是否允许编辑 |
|
|
105
|
+
| `formItemProps` | `ListTableFormItemPropsConfig` | 编辑器配置 |
|
|
106
|
+
| `resizable` | `boolean` | 单列是否允许调整宽度 |
|
|
107
|
+
| `draggable` | `boolean` | 单列是否允许拖拽 |
|
|
108
|
+
| `allowSort` | `boolean` | 是否开启排序 |
|
|
109
|
+
| `allowFilter` | `boolean` | 是否开启过滤 |
|
|
110
|
+
| `filterOptions` | `ListTableFilterOption[]` | 精确过滤选项 |
|
|
111
|
+
| `cellType` | `ListTableCellContent["type"]` | 内建单元格类型 |
|
|
112
|
+
| `moneyFormat` | `ListTableMoneyFormatOptions` | 金额格式配置，仅在 `cellType: "money"` 时生效 |
|
|
113
|
+
| `dataFormat` | `"default" \| "text" \| "number" \| "thousands" \| "decimal" \| ...` | 右键菜单设置的数据展示格式 |
|
|
114
|
+
| `cellStyle.verticalAlign` | `"top" \| "middle" \| "bottom"` | 表体垂直对齐 |
|
|
115
|
+
| `headerStyle.verticalAlign` | `"top" \| "middle" \| "bottom"` | 表头垂直对齐 |
|
|
116
|
+
| `render` | `(value, record, rowIndex, column) => ...` | 自定义渲染 |
|
|
117
|
+
| `onCell` | `(value, record, rowIndex, column) => { rowSpan?: number; colSpan?: number }` | 单元格跨度控制 |
|
|
118
|
+
| `summary` | `boolean \| ListTableSummaryConfig` | 汇总配置 |
|
|
119
|
+
| `summaryTitle` | `string` | 汇总标题文本 |
|
|
120
|
+
|
|
121
|
+
### 常见嵌套能力
|
|
122
|
+
|
|
123
|
+
| 配置 | 说明 |
|
|
124
|
+
| -------------- | ---------------------------------------------------------------------- |
|
|
125
|
+
| `query` | 排序、筛选、远程查询、自动合并单元格 |
|
|
126
|
+
| `rowSelector` | 空白整行选择器，单击选中一行、纵向拖拽选中连续多行 |
|
|
127
|
+
| `rowSelection` | checkbox / radio 行选择 |
|
|
128
|
+
| `expandable` | 树形数据、详情展开、展开列 |
|
|
129
|
+
| `pagination` | 按钮分页或滚动加载 |
|
|
130
|
+
| `rowDrag` | 行拖拽、跨表拖拽、拖放回调 |
|
|
131
|
+
| `contextMenu` | 复制、导出、排序、冻结、列显示、分组栏、对齐、数据格式、密度、缩放等菜单能力 |
|
|
132
|
+
|
|
133
|
+
分组功能默认关闭，只有显式传入 `grouping: {}` 才会启用右键菜单中的分组入口。`grouping.visible` 控制 Canvas 顶部分组栏初始显隐，默认 `false`；`grouping.columnKeys` 按顺序声明初始分组层级。显示分组栏后可将列头拖入栏内；分组列会从表头和表体隐藏，仅以 Canvas 标签展示，移除标签会立即恢复该列。右键分组栏可隐藏分组栏；`grouping.onChange` 会在标签增删时收到最新列 key 列表。
|
|
134
|
+
|
|
135
|
+
`rowSelection.selectRowByClick` 控制点击普通表体区域时是否同步切换 checkbox / radio 选择状态，默认关闭。该配置直接复用表格内部选择状态，无需通过外部 `key` 强制重新创建表格；查看详情等业务点击仍使用 `onRow().onClick`。
|
|
136
|
+
|
|
137
|
+
`rowSelector` 与 `rowSelection` 相互独立。默认在最左侧展示宽度为 `12px` 的空白选择器列；传入 `{ width: 32 }` 可自定义宽度，传入 `false` 可隐藏。该列只建立 Canvas 整行选区，不修改 checkbox / radio 的选中数据。
|
|
138
|
+
|
|
139
|
+
## 方法说明
|
|
140
|
+
|
|
141
|
+
| 方法 | 签名 | 说明 |
|
|
142
|
+
| ------------------ | ------------------------------------------------ | ----------------------------------------------------- |
|
|
143
|
+
| `constructor` | `new ListTable(container, options)` | 创建实例 |
|
|
144
|
+
| `mount` | `() => void` | 挂载表格 |
|
|
145
|
+
| `updateOptions` | `(options) => void` | 更新配置并刷新 |
|
|
146
|
+
| `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
|
|
147
|
+
| `validate` | `() => Promise<RecordType[]>` | 手动触发校验，失败时抛出 `ListTableValidationFailure` |
|
|
148
|
+
| `exportXlsx` | `(options?: ListTableExportXlsxOptions) => void` | 异步导出全部原始数据为 XLSX，可配置文件名和汇总行 |
|
|
149
|
+
| `scrollTo` | `(options: ListTableScrollToOptions) => void` | 滚动到指定行 |
|
|
150
|
+
| `destroy` | `() => void` | 销毁实例 |
|
|
151
|
+
|
|
152
|
+
列配置可通过 `settingTitle`、`initialHide`、`hideInSetting`、`disableHide` 约束列设置中的标题、初始显隐和隐藏权限。
|
|
153
|
+
|
|
154
|
+
## 内建单元格内容
|
|
155
|
+
|
|
156
|
+
`render` 支持直接返回结构化内容，内建类型包括：
|
|
157
|
+
|
|
158
|
+
- `text`
|
|
159
|
+
- `money`
|
|
160
|
+
- `image`
|
|
161
|
+
- `qrcode`
|
|
162
|
+
- `barcode`
|
|
163
|
+
- `progress`
|
|
164
|
+
- `chart`
|
|
165
|
+
- `rate`
|
|
166
|
+
- `button`
|
|
167
|
+
- `tag`
|
|
168
|
+
- `color`
|
|
169
|
+
- `icon`
|
|
170
|
+
- `checkbox`
|
|
171
|
+
- `radio`
|
|
172
|
+
- `switch`
|
|
173
|
+
- `link`
|
|
174
|
+
|
|
175
|
+
### 金额单元格示例
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
const columns = [
|
|
179
|
+
{
|
|
180
|
+
title: "金额",
|
|
181
|
+
dataIndex: "amount",
|
|
182
|
+
width: 140,
|
|
183
|
+
align: "right",
|
|
184
|
+
cellType: "money",
|
|
185
|
+
moneyFormat: {
|
|
186
|
+
symbol: "¥",
|
|
187
|
+
thousandsSeparator: true,
|
|
188
|
+
decimalPlaces: 2,
|
|
189
|
+
},
|
|
190
|
+
},
|
|
191
|
+
{
|
|
192
|
+
title: "结算金额",
|
|
193
|
+
dataIndex: "settlementAmount",
|
|
194
|
+
width: 160,
|
|
195
|
+
align: "right",
|
|
196
|
+
render(value) {
|
|
197
|
+
return {
|
|
198
|
+
type: "money",
|
|
199
|
+
value: value as number,
|
|
200
|
+
symbol: "$",
|
|
201
|
+
thousandsSeparator: ",",
|
|
202
|
+
decimalPlaces: 1,
|
|
203
|
+
};
|
|
204
|
+
},
|
|
205
|
+
},
|
|
206
|
+
];
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## 行点击事件
|
|
210
|
+
|
|
211
|
+
`onRow` 使用 AntD Table 风格的回调结构。由于表格由 Canvas 渲染，目前只支持整行点击事件；行高亮继续由表格内置选区处理。
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
const table = new ListTable(container, {
|
|
215
|
+
columns,
|
|
216
|
+
dataSource,
|
|
217
|
+
onRow: (record, rowIndex) => ({
|
|
218
|
+
onClick: (event) => {
|
|
219
|
+
console.log(record, rowIndex, event);
|
|
220
|
+
},
|
|
221
|
+
}),
|
|
222
|
+
});
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## 推荐搭配
|
|
226
|
+
|
|
227
|
+
- 原生 DOM 场景：直接使用 `ListTable`
|
|
228
|
+
- React 场景：优先使用 `@canvas-components/react-list-table`
|
|
229
|
+
- 二维码 / 条形码 / 图表单元格：配合 `@canvas-components/qrcode`、`@canvas-components/barcode`、`@canvas-components/chart`
|