@canvas-components/react-list-table 0.2.0 → 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.
Files changed (8) hide show
  1. package/README.md +137 -128
  2. package/dist/index.cjs +250 -60
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +6 -2
  5. package/dist/index.d.ts +6 -2
  6. package/dist/index.js +250 -60
  7. package/dist/index.js.map +1 -1
  8. package/package.json +2 -2
package/README.md CHANGED
@@ -1,128 +1,137 @@
1
- # @canvas-components/react-list-table
2
-
3
- `@canvas-components/react-list-table` 是 `@canvas-components/list-table` 的 React 适配层，负责把原生 Canvas 表格接入 React 应用，并提供更接近业务开发习惯的组件化入口。
4
-
5
- ## 功能作用
6
-
7
- - 提供 `ReactListTable` 组件
8
- - 内置工具栏、分页层、编辑层、tooltip、图片预览
9
- - 暴露 `ref` 方法，方便外部校验和滚动定位
10
- - 保持底层大数据性能和纯原生渲染能力
11
-
12
- ## 安装方法
13
-
14
- ```bash
15
- pnpm add @canvas-components/react-list-table @canvas-components/list-table react@^16.8 react-dom@^16.8
16
- ```
17
-
18
- 最低依赖版本：
19
-
20
- - `react >= 16.8.0`
21
- - `react-dom >= 16.8.0`
22
- - `Node.js >= 18.12.0`
23
- - `pnpm >= 9.0.0`
24
-
25
- ## 使用方法
26
-
27
- ```tsx
28
- import { useMemo, useRef } from "react";
29
- import {
30
- ReactListTable,
31
- type ReactListTableRef,
32
- } from "@canvas-components/react-list-table";
33
-
34
- interface UserRow {
35
- id: number;
36
- name: string;
37
- age: number;
38
- }
39
-
40
- export function DemoTable() {
41
- const tableRef = useRef<ReactListTableRef<UserRow> | null>(null);
42
-
43
- const columns = useMemo(
44
- () => [
45
- { key: "name", title: "姓名", dataIndex: "name", width: 180 },
46
- { key: "age", title: "年龄", dataIndex: "age", width: 120, align: "right" as const },
47
- ],
48
- [],
49
- );
50
-
51
- return (
52
- <ReactListTable<UserRow>
53
- ref={tableRef}
54
- rowKey="id"
55
- height={480}
56
- columns={columns}
57
- dataSource={[
58
- { id: 1, name: "张三", age: 28 },
59
- { id: 2, name: "李四", age: 31 },
60
- ]}
61
- toolbar={{ showRefresh: true, showExport: true }}
62
- />
63
- );
64
- }
65
- ```
66
-
67
- ## 属性说明
68
-
69
- ### `ReactListTableProps`
70
-
71
- `ReactListTableProps` 继承自 `ListTableOptions`，并额外补充 React 宿主相关能力。
72
-
73
- | 属性 | 类型 | 说明 |
74
- | --- | --- | --- |
75
- | `width` | `number \| string` | 表格宽度 |
76
- | `height` | `number \| string` | 表格高度 |
77
- | `emptyText` | `string` | 空状态文案 |
78
- | `scroll` | `ReactListTableScrollConfig` | React 风格滚动尺寸配置 |
79
- | `locale` | `ReactListTableLocale` | 本地化文案 |
80
- | `onChange` | `ListTableQueryChange<RecordType>` | 查询状态变更回调 |
81
- | `className` | `string` | 根节点类名 |
82
- | `style` | `CSSProperties` | 根节点样式 |
83
- | `title` | `ReactNode` | 标题栏左侧内容 |
84
- | `toolbar` | `false \| ReactListTableToolbarOptions` | 工具栏配置，传 `false` 隐藏 |
85
-
86
- 其余如 `columns`、`dataSource`、`rowSelection`、`expandable`、`pagination`、`rowDrag`、`draggable`、`resizable` 等属性与 `@canvas-components/list-table` 保持一致。
87
-
88
- ### `ReactListTableToolbarOptions`
89
-
90
- | 属性 | 类型 | 说明 |
91
- | --- | --- | --- |
92
- | `showRefresh` | `boolean` | 是否显示刷新按钮 |
93
- | `showFullscreen` | `boolean` | 是否显示全屏按钮 |
94
- | `showDensity` | `boolean` | 是否显示密度切换 |
95
- | `showColumnSetting` | `boolean` | 是否显示列设置 |
96
- | `columnSettingWidth` | `number \| string` | 列设置面板宽度 |
97
- | `showExport` | `boolean` | 是否显示导出按钮 |
98
- | `onRefresh` | `() => void` | 点击刷新回调 |
99
- | `onExport` | `() => void` | 自定义导出回调 |
100
- | `getFullscreenNode` | `() => HTMLElement \| null` | 自定义全屏节点 |
101
- | `extra` | `ReactNode` | 工具栏右侧额外内容 |
102
-
103
- ## 方法说明
104
-
105
- ### `ReactListTableRef`
106
-
107
- | 方法 | 签名 | 说明 |
108
- | --- | --- | --- |
109
- | `validate` | `() => Promise<RecordType[]>` | 触发表格校验 |
110
- | `scrollTo` | `(options) => void` | 滚动到指定行 |
111
- | `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
112
-
113
- ## 类型别名
114
-
115
- | 类型 | 说明 |
116
- | --- | --- |
117
- | `ReactListTableTableProps<RecordType>` | `ReactListTableProps<RecordType>` 的别名 |
118
- | `ReactListTableColumnType<RecordType>` | 单列类型别名 |
119
- | `ReactListTableColumnsType<RecordType>` | 列数组类型别名 |
120
- | `ReactListTableRowSelection<RecordType>` | 行选择类型别名 |
121
- | `ReactListTablePagination` | 分页类型别名 |
122
- | `ReactListTableQuery<RecordType>` | 查询类型别名 |
123
-
124
- ## 推荐场景
125
-
126
- - React 后台管理表格
127
- - 大数据量只读 / 可编辑表格
128
- - 需要原生性能但又希望保留 React 组件用法的场景
1
+ # @canvas-components/react-list-table
2
+
3
+ `@canvas-components/react-list-table` 是 `@canvas-components/list-table` 的 React 适配层，负责把原生 Canvas 表格接入 React 应用，并提供更接近业务开发习惯的组件化入口。
4
+
5
+ ## 功能作用
6
+
7
+ - 提供 `ReactListTable` 组件
8
+ - 内置工具栏、分页层、编辑层、tooltip、图片预览
9
+ - 暴露 `ref` 方法，方便外部校验和滚动定位
10
+ - 保持底层大数据性能和纯原生渲染能力
11
+
12
+ ## 安装方法
13
+
14
+ ```bash
15
+ pnpm add @canvas-components/react-list-table @canvas-components/list-table react@^16.8 react-dom@^16.8
16
+ ```
17
+
18
+ 最低依赖版本：
19
+
20
+ - `react >= 16.8.0`
21
+ - `react-dom >= 16.8.0`
22
+ - `Node.js >= 18.12.0`
23
+ - `pnpm >= 9.0.0`
24
+
25
+ ## 使用方法
26
+
27
+ ```tsx
28
+ import { useMemo, useRef } from "react";
29
+ import {
30
+ ReactListTable,
31
+ type ReactListTableRef,
32
+ } from "@canvas-components/react-list-table";
33
+
34
+ interface UserRow {
35
+ id: number;
36
+ name: string;
37
+ age: number;
38
+ }
39
+
40
+ export function DemoTable() {
41
+ const tableRef = useRef<ReactListTableRef<UserRow> | null>(null);
42
+
43
+ const columns = useMemo(
44
+ () => [
45
+ { key: "name", title: "姓名", dataIndex: "name", width: 180 },
46
+ {
47
+ key: "age",
48
+ title: "年龄",
49
+ dataIndex: "age",
50
+ width: 120,
51
+ align: "right" as const,
52
+ },
53
+ ],
54
+ [],
55
+ );
56
+
57
+ return (
58
+ <ReactListTable<UserRow>
59
+ ref={tableRef}
60
+ rowKey="id"
61
+ height={480}
62
+ columns={columns}
63
+ dataSource={[
64
+ { id: 1, name: "张三", age: 28 },
65
+ { id: 2, name: "李四", age: 31 },
66
+ ]}
67
+ toolbar={{ showRefresh: true, showExport: true }}
68
+ />
69
+ );
70
+ }
71
+ ```
72
+
73
+ ## 属性说明
74
+
75
+ ### `ReactListTableProps`
76
+
77
+ `ReactListTableProps` 继承自 `ListTableOptions`，并额外补充 React 宿主相关能力。
78
+
79
+ | 属性 | 类型 | 说明 |
80
+ | ----------- | --------------------------------------- | --------------------------- |
81
+ | `width` | `number \| string` | 表格宽度 |
82
+ | `height` | `number \| string` | 表格高度 |
83
+ | `emptyText` | `string` | 空状态文案 |
84
+ | `scroll` | `ReactListTableScrollConfig` | React 风格滚动尺寸配置 |
85
+ | `locale` | `ReactListTableLocale` | 本地化文案 |
86
+ | `onChange` | `ListTableQueryChange<RecordType>` | 查询状态变更回调 |
87
+ | `className` | `string` | 根节点类名 |
88
+ | `style` | `CSSProperties` | 根节点样式 |
89
+ | `title` | `ReactNode` | 标题栏左侧内容 |
90
+ | `toolbar` | `false \| ReactListTableToolbarOptions` | 工具栏配置，传 `false` 隐藏 |
91
+
92
+ 其余如 `columns`、`dataSource`、`rowSelection`、`expandable`、`pagination`、`rowDrag`、`draggable`、`resizable` 等属性与 `@canvas-components/list-table` 保持一致。
93
+
94
+ ### `ReactListTableToolbarOptions`
95
+
96
+ | 属性 | 类型 | 说明 |
97
+ | -------------------- | ---------------------------- | ---------------------------- |
98
+ | `showRefresh` | `boolean` | 是否显示刷新按钮 |
99
+ | `showFullscreen` | `boolean` | 是否显示全屏按钮 |
100
+ | `showDensity` | `boolean` | 是否显示密度切换 |
101
+ | `showColumnSetting` | `boolean` | 是否显示列设置 |
102
+ | `columnSettingWidth` | `number \| string` | 列设置面板宽度 |
103
+ | `columnSettingHeaderExtra` | `ReactNode` | 列设置标题区中重置按钮前的扩展内容 |
104
+ | `showExport` | `boolean` | 是否显示导出按钮 |
105
+ | `exportOptions` | `ListTableExportXlsxOptions` | 默认导出的文件名和汇总行配置 |
106
+ | `onRefresh` | `() => void` | 点击刷新回调 |
107
+ | `onExport` | `() => void` | 自定义导出回调 |
108
+ | `getFullscreenNode` | `() => HTMLElement \| null` | 自定义全屏节点 |
109
+ | `extra` | `ReactNode` | 工具栏右侧额外内容 |
110
+
111
+ ## 方法说明
112
+
113
+ ### `ReactListTableRef`
114
+
115
+ | 方法 | 签名 | 说明 |
116
+ | ------------------ | ------------------------------------------------ | ------------------------------- |
117
+ | `validate` | `() => Promise<RecordType[]>` | 触发表格校验 |
118
+ | `exportXlsx` | `(options?: ListTableExportXlsxOptions) => void` | 导出 XLSX，可配置文件名和汇总行 |
119
+ | `scrollTo` | `(options) => void` | 滚动到指定行 |
120
+ | `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
121
+
122
+ ## 类型别名
123
+
124
+ | 类型 | 说明 |
125
+ | ---------------------------------------- | ---------------------------------------- |
126
+ | `ReactListTableTableProps<RecordType>` | `ReactListTableProps<RecordType>` 的别名 |
127
+ | `ReactListTableColumnType<RecordType>` | 单列类型别名 |
128
+ | `ReactListTableColumnsType<RecordType>` | 列数组类型别名 |
129
+ | `ReactListTableRowSelection<RecordType>` | 行选择类型别名 |
130
+ | `ReactListTablePagination` | 分页类型别名 |
131
+ | `ReactListTableQuery<RecordType>` | 查询类型别名 |
132
+
133
+ ## 推荐场景
134
+
135
+ - React 后台管理表格
136
+ - 大数据量只读 / 可编辑表格
137
+ - 需要原生性能但又希望保留 React 组件用法的场景