@canvas-components/react-pivot-table

@canvas-components/react-pivot-table 是 @canvas-components/pivot-table 的 React 适配层，在保留原生 Canvas 数据透视表性能的同时，提供标题栏、字段配置面板、图表联动和 React ref 接口。

示例效果

功能作用

• 提供 ReactPivotTable 组件
• 支持行、列、指标的多层聚合与虚拟滚动
• 支持字段面板配置和透视图表联动
• 暴露选择、展开、筛选、排序、导出和状态快照方法
• 聚合、布局和 Canvas 渲染复用纯原生 pivot-table 内核

安装方法

pnpm add @canvas-components/react-pivot-table @canvas-components/pivot-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 { ReactPivotTable } from "@canvas-components/react-pivot-table";

interface SalesRecord {
  region: string;
  city: string;
  year: number;
  sales: number;
}

export function SalesPivotTable(props: { data: SalesRecord[] }) {
  return (
    <div style={{ width: "100%", height: 560 }}>
      <ReactPivotTable<SalesRecord>
        title="销售数据透视表"
        dataSource={props.data}
        rows={[
          { key: "region", title: "区域", dataIndex: "region" },
          { key: "city", title: "城市", dataIndex: "city" },
        ]}
        columns={[{ key: "year", title: "年份", dataIndex: "year" }]}
        indicators={[
          {
            key: "sales",
            title: "销售额",
            dataIndex: "sales",
            aggregator: "sum",
          },
        ]}
        totals={{
          showRowSubtotals: true,
          showColumnGrandTotal: true,
          showRowGrandTotal: true,
        }}
      />
    </div>
  );
}

属性说明

ReactPivotTableProps

ReactPivotTableProps 继承自 PivotTableOptions，并增加 React 宿主相关属性。

其余 dataSource、rows、columns、indicators、totals、filters、sorts 和虚拟滚动等属性与 @canvas-components/pivot-table 保持一致。

统一切换调试模式

ReactPivotTableDebugProvider 可为后代中的全部 ReactPivotTable 同步开启核心调试模式，并保留每个表格自身的 debug 配置：

import {
  ReactPivotTable,
  ReactPivotTableDebugProvider,
} from "@canvas-components/react-pivot-table";

<ReactPivotTableDebugProvider enabled={debuggerEnabled}>
  <ReactPivotTable
    {...props}
    debug={{ showBodyBounds: false, logDrawCalls: true }}
  />
</ReactPivotTableDebugProvider>;

ReactPivotTableCustomizationOptions

实例方法

通过 ReactPivotTableRef 可以访问以下能力：

• 获取透视模型、可见行列节点和单元格明细记录
• 读取或设置选择状态，并滚动到指定单元格
• 展开、收起行列节点或全部节点
• 设置维度筛选、维度排序和指标排序
• 导出 CSV、XLSX
• 获取和恢复版本化状态快照
• 获取调试快照

XLSX 导出弹窗

右键导出 XLSX 使用与 ReactListTable 相同的导出弹窗和配置表，支持修改文件名（后缀固定）、勾选列、拖拽调整列顺序、数据升降序排序，以及选择是否导出汇总行。汇总支持方式、前缀、小数位数、取整方式和保留无效零；默认带入原表配置，不修改原表。

通过 exportOptions.fileName 指定默认名称，exportOptions.promptFileName: false 跳过弹窗。弹窗关闭后销毁配置表，配置表不提供右键菜单。原生 ref.exportXlsx() 仍是返回字节的接口，不触发弹窗。

推荐场景

• React 数据分析后台
• 大数据量多维聚合报表
• 需要字段拖放配置或图表联动的数据透视场景
• 需要原生 Canvas 性能和 React 组件用法的场景