@canvas-components/list-table 0.2.1 → 0.2.2
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 +204 -198
- package/dist/index.cjs +639 -381
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +38 -5
- package/dist/index.d.ts +38 -5
- package/dist/index.js +640 -382
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,198 +1,204 @@
|
|
|
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` | `number`
|
|
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
|
+
## 方法说明
|
|
131
|
+
|
|
132
|
+
| 方法 | 签名 | 说明 |
|
|
133
|
+
| ------------------ | ------------------------------------------------ | ----------------------------------------------------- |
|
|
134
|
+
| `constructor` | `new ListTable(container, options)` | 创建实例 |
|
|
135
|
+
| `mount` | `() => void` | 挂载表格 |
|
|
136
|
+
| `updateOptions` | `(options) => void` | 更新配置并刷新 |
|
|
137
|
+
| `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
|
|
138
|
+
| `validate` | `() => Promise<RecordType[]>` | 手动触发校验，失败时抛出 `ListTableValidationFailure` |
|
|
139
|
+
| `exportXlsx` | `(options?: ListTableExportXlsxOptions) => void` | 异步导出全部原始数据为 XLSX，可配置文件名和汇总行 |
|
|
140
|
+
| `scrollTo` | `(options: ListTableScrollToOptions) => void` | 滚动到指定行 |
|
|
141
|
+
| `destroy` | `() => void` | 销毁实例 |
|
|
142
|
+
|
|
143
|
+
列配置可通过 `settingTitle`、`initialHide`、`hideInSetting`、`disableHide` 约束列设置中的标题、初始显隐和隐藏权限。
|
|
144
|
+
|
|
145
|
+
## 内建单元格内容
|
|
146
|
+
|
|
147
|
+
`render` 支持直接返回结构化内容，内建类型包括：
|
|
148
|
+
|
|
149
|
+
- `text`
|
|
150
|
+
- `money`
|
|
151
|
+
- `image`
|
|
152
|
+
- `qrcode`
|
|
153
|
+
- `barcode`
|
|
154
|
+
- `progress`
|
|
155
|
+
- `chart`
|
|
156
|
+
- `rate`
|
|
157
|
+
- `button`
|
|
158
|
+
- `tag`
|
|
159
|
+
- `color`
|
|
160
|
+
- `icon`
|
|
161
|
+
- `checkbox`
|
|
162
|
+
- `radio`
|
|
163
|
+
- `switch`
|
|
164
|
+
- `link`
|
|
165
|
+
|
|
166
|
+
### 金额单元格示例
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
const columns = [
|
|
170
|
+
{
|
|
171
|
+
title: "金额",
|
|
172
|
+
dataIndex: "amount",
|
|
173
|
+
width: 140,
|
|
174
|
+
align: "right",
|
|
175
|
+
cellType: "money",
|
|
176
|
+
moneyFormat: {
|
|
177
|
+
symbol: "¥",
|
|
178
|
+
thousandsSeparator: true,
|
|
179
|
+
decimalPlaces: 2,
|
|
180
|
+
},
|
|
181
|
+
},
|
|
182
|
+
{
|
|
183
|
+
title: "结算金额",
|
|
184
|
+
dataIndex: "settlementAmount",
|
|
185
|
+
width: 160,
|
|
186
|
+
align: "right",
|
|
187
|
+
render(value) {
|
|
188
|
+
return {
|
|
189
|
+
type: "money",
|
|
190
|
+
value: value as number,
|
|
191
|
+
symbol: "$",
|
|
192
|
+
thousandsSeparator: ",",
|
|
193
|
+
decimalPlaces: 1,
|
|
194
|
+
};
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
];
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## 推荐搭配
|
|
201
|
+
|
|
202
|
+
- 原生 DOM 场景：直接使用 `ListTable`
|
|
203
|
+
- React 场景：优先使用 `@canvas-components/react-list-table`
|
|
204
|
+
- 二维码 / 条形码 / 图表单元格：配合 `@canvas-components/qrcode`、`@canvas-components/barcode`、`@canvas-components/chart`
|