@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 宿主相关属性。

| 属性 | 类型 | 说明 | | --------------- | ------------------------------------------------ | ---------------------------- | | className | string | 根节点类名 | | style | CSSProperties | 根节点样式 | | title | ReactNode | 标题栏内容 | | customization | boolean \| ReactPivotTableCustomizationOptions | 是否启用字段配置面板及其配置 |

其余 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

| 属性 | 类型 | 说明 | | ---------------- | ------------------ | ------------------------ | | fields | PivotField[] | 可参与透视配置的全部字段 | | open | boolean | 受控字段面板开关 | | defaultOpen | boolean | 非受控字段面板初始状态 | | layout | PivotFieldLayout | 受控字段区域布局 | | defaultLayout | PivotFieldLayout | 非受控字段区域初始布局 | | panelWidth | number | 字段面板宽度 | | onOpenChange | (open) => void | 面板开关变化回调 | | onLayoutChange | (layout) => void | 字段区域布局变化回调 | | onFieldChange | (field) => void | 字段配置变化回调 |

实例方法

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

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

推荐场景

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