@canvas-components/react-table

@canvas-components/react-table 是 @canvas-components/core 的 React 适配层，负责把原生 Canvas 表格接入 React 应用，并提供更接近业务开发习惯的组件化入口。

功能作用

• 提供 ReactCanvasTable 组件
• 内置工具栏、分页层、编辑层、tooltip、图片预览
• 暴露 ref 方法，方便外部校验和滚动定位
• 保持底层大数据性能和纯原生渲染能力

安装方法

pnpm add @canvas-components/react-table @canvas-components/core 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

使用方法

import { useMemo, useRef } from "react";
import {
  ReactCanvasTable,
  type ReactCanvasTableRef,
} from "@canvas-components/react-table";

interface UserRow {
  id: number;
  name: string;
  age: number;
}

export function DemoTable() {
  const tableRef = useRef<ReactCanvasTableRef<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 (
    <ReactCanvasTable<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 }}
    />
  );
}

属性说明

ReactCanvasTableProps

ReactCanvasTableProps 继承自 CanvasTableOptions，并额外补充 React 宿主相关能力。

| 属性 | 类型 | 说明 | | --- | --- | --- | | width | number \| string | 表格宽度 | | height | number \| string | 表格高度 | | emptyText | string | 空状态文案 | | scroll | ReactCanvasTableScrollConfig | React 风格滚动尺寸配置 | | locale | ReactCanvasTableLocale | 本地化文案 | | onChange | CanvasTableQueryChange<RecordType> | 查询状态变更回调 | | className | string | 根节点类名 | | style | CSSProperties | 根节点样式 | | title | ReactNode | 标题栏左侧内容 | | toolbar | false \| ReactCanvasTableToolbarOptions | 工具栏配置，传 false 隐藏 |

其余如 columns、dataSource、rowSelection、expandable、pagination、rowDrag、draggable、resizable 等属性与 @canvas-components/core 保持一致。

ReactCanvasTableToolbarOptions

| 属性 | 类型 | 说明 | | --- | --- | --- | | showRefresh | boolean | 是否显示刷新按钮 | | showFullscreen | boolean | 是否显示全屏按钮 | | showDensity | boolean | 是否显示密度切换 | | showColumnSetting | boolean | 是否显示列设置 | | columnSettingWidth | number \| string | 列设置面板宽度 | | showExport | boolean | 是否显示导出按钮 | | onRefresh | () => void | 点击刷新回调 | | onExport | () => void | 自定义导出回调 | | getFullscreenNode | () => HTMLElement \| null | 自定义全屏节点 | | extra | ReactNode | 工具栏右侧额外内容 |

方法说明

ReactCanvasTableRef

| 方法 | 签名 | 说明 | | --- | --- | --- | | validate | () => Promise<RecordType[]> | 触发表格校验 | | scrollTo | (options) => void | 滚动到指定行 | | getDebugSnapshot | () => CanvasTableDebugSnapshot \| null | 获取调试快照 |

类型别名

| 类型 | 说明 | | --- | --- | | ReactCanvasTableTableProps<RecordType> | ReactCanvasTableProps<RecordType> 的别名 | | ReactCanvasTableColumnType<RecordType> | 单列类型别名 | | ReactCanvasTableColumnsType<RecordType> | 列数组类型别名 | | ReactCanvasTableRowSelection<RecordType> | 行选择类型别名 | | ReactCanvasTablePagination | 分页类型别名 | | ReactCanvasTableQuery<RecordType> | 查询类型别名 |

推荐场景

• React 后台管理表格
• 大数据量只读 / 可编辑表格
• 需要原生性能但又希望保留 React 组件用法的场景