@canvas-components/react-list-table 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 canvas-components contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @canvas-components/react-list-table
+
+`@canvas-components/react-list-table` 是 `@canvas-components/list-table` 的 React 适配层，负责把原生 Canvas 表格接入 React 应用，并提供更接近业务开发习惯的组件化入口。
+
+## 功能作用
+
+- 提供 `ReactListTable` 组件
+- 内置工具栏、分页层、编辑层、tooltip、图片预览
+- 暴露 `ref` 方法，方便外部校验和滚动定位
+- 保持底层大数据性能和纯原生渲染能力
+
+## 安装方法
+
+```bash
+pnpm add @canvas-components/react-list-table @canvas-components/list-table react@^16.8 react-dom@^16.8
+```
+
+最低依赖版本：
+
+- `react >= 16.8.0`
+- `react-dom >= 16.8.0`
+- `Node.js >= 18.12.0`
+- `pnpm >= 9.0.0`
+
+## 使用方法
+
+```tsx
+import { useMemo, useRef } from "react";
+import {
+  ReactListTable,
+  type ReactListTableRef,
+} from "@canvas-components/react-list-table";
+
+interface UserRow {
+  id: number;
+  name: string;
+  age: number;
+}
+
+export function DemoTable() {
+  const tableRef = useRef<ReactListTableRef<UserRow> | null>(null);
+
+  const columns = useMemo(
+    () => [
+      { key: "name", title: "姓名", dataIndex: "name", width: 180 },
+      { key: "age", title: "年龄", dataIndex: "age", width: 120, align: "right" as const },
+    ],
+    [],
+  );
+
+  return (
+    <ReactListTable<UserRow>
+      ref={tableRef}
+      rowKey="id"
+      height={480}
+      columns={columns}
+      dataSource={[
+        { id: 1, name: "张三", age: 28 },
+        { id: 2, name: "李四", age: 31 },
+      ]}
+      toolbar={{ showRefresh: true, showExport: true }}
+    />
+  );
+}
+```
+
+## 属性说明
+
+### `ReactListTableProps`
+
+`ReactListTableProps` 继承自 `ListTableOptions`，并额外补充 React 宿主相关能力。
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `width` | `number \| string` | 表格宽度 |
+| `height` | `number \| string` | 表格高度 |
+| `emptyText` | `string` | 空状态文案 |
+| `scroll` | `ReactListTableScrollConfig` | React 风格滚动尺寸配置 |
+| `locale` | `ReactListTableLocale` | 本地化文案 |
+| `onChange` | `ListTableQueryChange<RecordType>` | 查询状态变更回调 |
+| `className` | `string` | 根节点类名 |
+| `style` | `CSSProperties` | 根节点样式 |
+| `title` | `ReactNode` | 标题栏左侧内容 |
+| `toolbar` | `false \| ReactListTableToolbarOptions` | 工具栏配置，传 `false` 隐藏 |
+
+其余如 `columns`、`dataSource`、`rowSelection`、`expandable`、`pagination`、`rowDrag`、`draggable`、`resizable` 等属性与 `@canvas-components/list-table` 保持一致。
+
+### `ReactListTableToolbarOptions`
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `showRefresh` | `boolean` | 是否显示刷新按钮 |
+| `showFullscreen` | `boolean` | 是否显示全屏按钮 |
+| `showDensity` | `boolean` | 是否显示密度切换 |
+| `showColumnSetting` | `boolean` | 是否显示列设置 |
+| `columnSettingWidth` | `number \| string` | 列设置面板宽度 |
+| `showExport` | `boolean` | 是否显示导出按钮 |
+| `onRefresh` | `() => void` | 点击刷新回调 |
+| `onExport` | `() => void` | 自定义导出回调 |
+| `getFullscreenNode` | `() => HTMLElement \| null` | 自定义全屏节点 |
+| `extra` | `ReactNode` | 工具栏右侧额外内容 |
+
+## 方法说明
+
+### `ReactListTableRef`
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `validate` | `() => Promise<RecordType[]>` | 触发表格校验 |
+| `scrollTo` | `(options) => void` | 滚动到指定行 |
+| `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
+
+## 类型别名
+
+| 类型 | 说明 |
+| --- | --- |
+| `ReactListTableTableProps<RecordType>` | `ReactListTableProps<RecordType>` 的别名 |
+| `ReactListTableColumnType<RecordType>` | 单列类型别名 |
+| `ReactListTableColumnsType<RecordType>` | 列数组类型别名 |
+| `ReactListTableRowSelection<RecordType>` | 行选择类型别名 |
+| `ReactListTablePagination` | 分页类型别名 |
+| `ReactListTableQuery<RecordType>` | 查询类型别名 |
+
+## 推荐场景
+
+- React 后台管理表格
+- 大数据量只读 / 可编辑表格
+- 需要原生性能但又希望保留 React 组件用法的场景