@canvas-components/list-table 0.2.1 → 0.2.3
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 +222 -198
- package/dist/index.cjs +651 -381
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +52 -5
- package/dist/index.d.ts +52 -5
- package/dist/index.js +652 -382
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,198 +1,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`
|
|
59
|
-
| `rowKey`
|
|
60
|
-
| `columns`
|
|
61
|
-
| `width`
|
|
62
|
-
| `height`
|
|
63
|
-
| `dataSource`
|
|
64
|
-
| `emptyText`
|
|
65
|
-
| `theme`
|
|
66
|
-
| `striped`
|
|
67
|
-
| `highlightMode`
|
|
68
|
-
| `contextMenu`
|
|
69
|
-
| `rowHeight`
|
|
70
|
-
| `headerRowHeight`
|
|
71
|
-
| `summaryRowHeight` | `number`
|
|
72
|
-
| `overscanRowCount` | `number`
|
|
73
|
-
| `query`
|
|
74
|
-
| `rowSelection`
|
|
75
|
-
| `expandable`
|
|
76
|
-
| `pagination`
|
|
77
|
-
| `scrollbar`
|
|
78
|
-
| `carouselScroll`
|
|
79
|
-
| `stretchColumns`
|
|
80
|
-
| `resizable`
|
|
81
|
-
| `storageKey`
|
|
82
|
-
| `draggable`
|
|
83
|
-
| `tableId`
|
|
84
|
-
| `rowDrag`
|
|
85
|
-
| `debug`
|
|
86
|
-
|
|
87
|
-
### 列配置 `ListTableColumn`
|
|
88
|
-
|
|
89
|
-
| 属性
|
|
90
|
-
|
|
|
91
|
-
| `key`
|
|
92
|
-
| `title`
|
|
93
|
-
| `dataIndex`
|
|
94
|
-
| `children`
|
|
95
|
-
| `width`
|
|
96
|
-
| `minWidth` / `maxWidth`
|
|
97
|
-
| `align`
|
|
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
|
-
|
|
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
|
+
| `rowHeight` | `number \| "auto"` | 行高 |
|
|
70
|
+
| `headerRowHeight` | `number` | 表头单行高度 |
|
|
71
|
+
| `summaryRowHeight` | `number` | 汇总行高度 |
|
|
72
|
+
| `overscanRowCount` | `number` | 虚拟滚动预渲染行数 |
|
|
73
|
+
| `query` | `ListTableQueryOptions` | 排序、过滤、合并单元格配置 |
|
|
74
|
+
| `rowSelection` | `ListTableRowSelectionOptions` | 行选择配置 |
|
|
75
|
+
| `expandable` | `ListTableExpandableOptions` | 树表 / 展开行配置 |
|
|
76
|
+
| `pagination` | `false \| ListTablePaginationOptions` | 分页或滚动加载配置 |
|
|
77
|
+
| `scrollbar` | `ListTableScrollbarOptions` | 滚动条配置 |
|
|
78
|
+
| `carouselScroll` | `ListTableCarouselScrollOptions` | 自动轮播滚动配置 |
|
|
79
|
+
| `stretchColumns` | `boolean` | 列总宽不足时是否拉伸补齐 |
|
|
80
|
+
| `resizable` | `boolean` | 是否开启列宽拖拽 |
|
|
81
|
+
| `storageKey` | `string` | 持久化键 |
|
|
82
|
+
| `draggable` | `boolean` | 是否开启列拖拽排序 |
|
|
83
|
+
| `tableId` | `string` | 表格唯一标识 |
|
|
84
|
+
| `rowDrag` | `ListTableRowDragOptions` | 行拖拽配置 |
|
|
85
|
+
| `debug` | `ListTableDebugOptions` | 调试配置 |
|
|
86
|
+
|
|
87
|
+
### 列配置 `ListTableColumn`
|
|
88
|
+
|
|
89
|
+
| 属性 | 类型 | 说明 |
|
|
90
|
+
| --------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
|
|
91
|
+
| `key` | `string` | 列唯一标识 |
|
|
92
|
+
| `title` | `string` | 列标题 |
|
|
93
|
+
| `dataIndex` | `string \| number \| Array<string \| number>` | 取值路径 |
|
|
94
|
+
| `children` | `ListTableColumn[]` | 子列，用于多级表头 |
|
|
95
|
+
| `width` | `number` | 列宽 |
|
|
96
|
+
| `minWidth` / `maxWidth` | `number` | 允许调整的最小 / 最大列宽 |
|
|
97
|
+
| `align` | `"left" \| "center" \| "right"` | 内容对齐 |
|
|
98
|
+
| `headerAlign` | `"left" \| "center" \| "right"` | 表头水平对齐，未传时回退到 `align` |
|
|
99
|
+
| `fixed` | `"left" \| "right"` | 固定列 |
|
|
100
|
+
| `hidden` | `boolean` | 是否隐藏 |
|
|
101
|
+
| `ellipsis` | `boolean` | 超出是否省略 |
|
|
102
|
+
| `editable` | `boolean \| (text, record, index) => boolean` | 是否允许编辑 |
|
|
103
|
+
| `formItemProps` | `ListTableFormItemPropsConfig` | 编辑器配置 |
|
|
104
|
+
| `resizable` | `boolean` | 单列是否允许调整宽度 |
|
|
105
|
+
| `draggable` | `boolean` | 单列是否允许拖拽 |
|
|
106
|
+
| `allowSort` | `boolean` | 是否开启排序 |
|
|
107
|
+
| `allowFilter` | `boolean` | 是否开启过滤 |
|
|
108
|
+
| `filterOptions` | `ListTableFilterOption[]` | 精确过滤选项 |
|
|
109
|
+
| `cellType` | `ListTableCellContent["type"]` | 内建单元格类型 |
|
|
110
|
+
| `moneyFormat` | `ListTableMoneyFormatOptions` | 金额格式配置，仅在 `cellType: "money"` 时生效 |
|
|
111
|
+
| `dataFormat` | `"default" \| "number" \| "thousands" \| "money"` | 右键菜单设置的数据展示格式 |
|
|
112
|
+
| `cellStyle.verticalAlign` | `"top" \| "middle" \| "bottom"` | 表体垂直对齐 |
|
|
113
|
+
| `headerStyle.verticalAlign` | `"top" \| "middle" \| "bottom"` | 表头垂直对齐 |
|
|
114
|
+
| `render` | `(value, record, rowIndex, column) => ...` | 自定义渲染 |
|
|
115
|
+
| `onCell` | `(value, record, rowIndex, column) => { rowSpan?: number; colSpan?: number }` | 单元格跨度控制 |
|
|
116
|
+
| `summary` | `boolean \| ListTableSummaryConfig` | 汇总配置 |
|
|
117
|
+
| `summaryTitle` | `string` | 汇总标题文本 |
|
|
118
|
+
|
|
119
|
+
### 常见嵌套能力
|
|
120
|
+
|
|
121
|
+
| 配置 | 说明 |
|
|
122
|
+
| -------------- | -------------------------------------------------------------- |
|
|
123
|
+
| `query` | 排序、筛选、远程查询、自动合并单元格 |
|
|
124
|
+
| `rowSelection` | checkbox / radio 行选择 |
|
|
125
|
+
| `expandable` | 树形数据、详情展开、展开列 |
|
|
126
|
+
| `pagination` | 按钮分页或滚动加载 |
|
|
127
|
+
| `rowDrag` | 行拖拽、跨表拖拽、拖放回调 |
|
|
128
|
+
| `contextMenu` | 复制、导出、冻结、列显示、对齐、数据格式、密度、缩放等菜单能力 |
|
|
129
|
+
|
|
130
|
+
`rowSelection.selectRowByClick` 控制点击普通表体区域时是否同步切换 checkbox / radio 选择状态，默认关闭。该配置直接复用表格内部选择状态，无需通过外部 `key` 强制重新创建表格；查看详情等业务点击仍使用 `onRow().onClick`。
|
|
131
|
+
|
|
132
|
+
## 方法说明
|
|
133
|
+
|
|
134
|
+
| 方法 | 签名 | 说明 |
|
|
135
|
+
| ------------------ | ------------------------------------------------ | ----------------------------------------------------- |
|
|
136
|
+
| `constructor` | `new ListTable(container, options)` | 创建实例 |
|
|
137
|
+
| `mount` | `() => void` | 挂载表格 |
|
|
138
|
+
| `updateOptions` | `(options) => void` | 更新配置并刷新 |
|
|
139
|
+
| `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
|
|
140
|
+
| `validate` | `() => Promise<RecordType[]>` | 手动触发校验，失败时抛出 `ListTableValidationFailure` |
|
|
141
|
+
| `exportXlsx` | `(options?: ListTableExportXlsxOptions) => void` | 异步导出全部原始数据为 XLSX，可配置文件名和汇总行 |
|
|
142
|
+
| `scrollTo` | `(options: ListTableScrollToOptions) => void` | 滚动到指定行 |
|
|
143
|
+
| `destroy` | `() => void` | 销毁实例 |
|
|
144
|
+
|
|
145
|
+
列配置可通过 `settingTitle`、`initialHide`、`hideInSetting`、`disableHide` 约束列设置中的标题、初始显隐和隐藏权限。
|
|
146
|
+
|
|
147
|
+
## 内建单元格内容
|
|
148
|
+
|
|
149
|
+
`render` 支持直接返回结构化内容，内建类型包括：
|
|
150
|
+
|
|
151
|
+
- `text`
|
|
152
|
+
- `money`
|
|
153
|
+
- `image`
|
|
154
|
+
- `qrcode`
|
|
155
|
+
- `barcode`
|
|
156
|
+
- `progress`
|
|
157
|
+
- `chart`
|
|
158
|
+
- `rate`
|
|
159
|
+
- `button`
|
|
160
|
+
- `tag`
|
|
161
|
+
- `color`
|
|
162
|
+
- `icon`
|
|
163
|
+
- `checkbox`
|
|
164
|
+
- `radio`
|
|
165
|
+
- `switch`
|
|
166
|
+
- `link`
|
|
167
|
+
|
|
168
|
+
### 金额单元格示例
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
const columns = [
|
|
172
|
+
{
|
|
173
|
+
title: "金额",
|
|
174
|
+
dataIndex: "amount",
|
|
175
|
+
width: 140,
|
|
176
|
+
align: "right",
|
|
177
|
+
cellType: "money",
|
|
178
|
+
moneyFormat: {
|
|
179
|
+
symbol: "¥",
|
|
180
|
+
thousandsSeparator: true,
|
|
181
|
+
decimalPlaces: 2,
|
|
182
|
+
},
|
|
183
|
+
},
|
|
184
|
+
{
|
|
185
|
+
title: "结算金额",
|
|
186
|
+
dataIndex: "settlementAmount",
|
|
187
|
+
width: 160,
|
|
188
|
+
align: "right",
|
|
189
|
+
render(value) {
|
|
190
|
+
return {
|
|
191
|
+
type: "money",
|
|
192
|
+
value: value as number,
|
|
193
|
+
symbol: "$",
|
|
194
|
+
thousandsSeparator: ",",
|
|
195
|
+
decimalPlaces: 1,
|
|
196
|
+
};
|
|
197
|
+
},
|
|
198
|
+
},
|
|
199
|
+
];
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## 行点击事件
|
|
203
|
+
|
|
204
|
+
`onRow` 使用 AntD Table 风格的回调结构。由于表格由 Canvas 渲染，目前只支持整行点击事件；行高亮继续由表格内置选区处理。
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
const table = new ListTable(container, {
|
|
208
|
+
columns,
|
|
209
|
+
dataSource,
|
|
210
|
+
onRow: (record, rowIndex) => ({
|
|
211
|
+
onClick: (event) => {
|
|
212
|
+
console.log(record, rowIndex, event);
|
|
213
|
+
},
|
|
214
|
+
}),
|
|
215
|
+
});
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## 推荐搭配
|
|
219
|
+
|
|
220
|
+
- 原生 DOM 场景：直接使用 `ListTable`
|
|
221
|
+
- React 场景：优先使用 `@canvas-components/react-list-table`
|
|
222
|
+
- 二维码 / 条形码 / 图表单元格：配合 `@canvas-components/qrcode`、`@canvas-components/barcode`、`@canvas-components/chart`
|