@canvas-components/react-list-table

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

通过顶层 loading 属性控制数据加载状态：<ReactListTable loading={loading} dataSource={rows} columns={columns} />。加载期间展示加载提示并保留汇总标题；加载完成后，组件自动计算并统一展示完整汇总结果。服务端汇总可通过 query.summaryValues 提供，业务侧无需单独管理汇总计算状态。

示例效果

完整示例图集

功能作用

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

安装方法

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

使用方法

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 | 列设置面板宽度 | | columnSettingHeaderExtra | ReactNode | 列设置标题区中重置按钮前的扩展内容 | | showExport | boolean | 是否显示导出按钮 | | exportOptions | ListTableExportXlsxOptions | 默认导出的文件名和汇总行配置 | | onRefresh | () => void | 点击刷新回调 | | onExport | () => void | 自定义导出回调 | | getFullscreenNode | () => HTMLElement \| null | 自定义全屏节点 | | extra | ReactNode | 工具栏右侧额外内容 |

统一切换调试模式

ReactListTableDebugProvider 可为后代中的全部 ReactListTable 同步开启核心调试模式，并默认显示表头、表体、固定列分割线、命中区域和表头操作区。表格自身通过 debug 传入的其他选项仍会保留，也可以显式关闭某个可视化项：

import {
  ReactListTable,
  ReactListTableDebugProvider,
} from "@canvas-components/react-list-table";

<ReactListTableDebugProvider enabled={statsEnabled}>
  <ReactListTable
    columns={columns}
    dataSource={dataSource}
    debug={{ showBodyBounds: true }}
  />
</ReactListTableDebugProvider>;

方法说明

ReactListTableRef

| 方法 | 签名 | 说明 | | ------------------ | ------------------------------------------------ | ------------------------------- | | validate | () => Promise<RecordType[]> | 触发表格校验 | | exportXlsx | (options?: ListTableExportXlsxOptions) => void | 导出 XLSX，可配置文件名和汇总行 | | scrollTo | (options) => void | 滚动到指定行 | | getDebugSnapshot | () => ListTableDebugSnapshot \| null | 获取调试快照 |

类型别名

| 类型 | 说明 | | ---------------------------------------- | ---------------------------------------- | | ReactListTableTableProps<RecordType> | ReactListTableProps<RecordType> 的别名 | | ReactListTableColumnType<RecordType> | 单列类型别名 | | ReactListTableColumnsType<RecordType> | 列数组类型别名 | | ReactListTableRowSelection<RecordType> | 行选择类型别名 | | ReactListTablePagination | 分页类型别名 | | ReactListTableQuery<RecordType> | 查询类型别名 |

推荐场景

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