@canvas-components/pivot-table

独立于 list-table 的纯原生数据透视表内核。包内不依赖 React，React 接入由 @canvas-components/react-pivot-table 提供。

能力

• 双轴多级维度树与稳定节点 ID
• sum、avg、count、distinctCount、rowCount、mergedRowCount、min、max 和自定义聚合器
• 稀疏聚合、小计、总计和多指标行列布局
• 四区 Canvas、虚拟滚动、展开收起、拖拽矩形选区和下钻
• 支持单元格、矩形选区与指标整列复制
• 维度成员排序与聚合前过滤；指标表头支持按汇总值排序、按值或按条件筛选行
• CSV/XLSX 导出与版本化状态快照

React 示例

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

<ReactPivotTable
  dataSource={records}
  rows={[{ dataIndex: "region", allowFilter: true }]}
  columns={[{ key: "year", dataIndex: "year" }]}
  indicators={[{ key: "sales", dataIndex: "sales", aggregator: "sum" }]}
/>;

rows 与 columns 的字段命名、render 回调及排序过滤配置与 ListTableColumn 保持一致，可以从 ListTable 列配置中直接选取维度列。 PivotTable 会在未提供 key 时使用 dataIndex 生成稳定维度标识； defaultExpandDepth 是透视维度额外支持的展开配置。

维度过滤发生在聚合前；指标表头过滤按当前列的汇总值筛选行分组，并重新计算总计。指标表头默认显示排序和筛选图标，可分别设置 allowSort: false、allowFilter: false 关闭。filters、sorts、selection 和 expandedRowKeys/expandedColumnKeys 可受控；不传时由实例维护。

汇总行右键的“汇总方式”支持标题、求和、平均值、计数、去重计数、行数、合并行数、最小值、最大值、展示方式前缀、取消汇总、小数位数、取整方式及保留无效零。“合并行数”统计当前汇总范围内不同的完整行维度组合；取消汇总仅清除当前指标的汇总值，保留标题和普通数据格。上述汇总配置可通过指标的 summaryAggregator、summaryTitle、summaryShowTypePrefix、summaryDisabled、precision、summaryRoundingMode 和 summaryPreserveTrailingZeros 设置。

汇总方式前缀只绘制在行小计、行总计中；普通数据行（包括与列总计相交的单元格）只显示数值。表头右键“自动调整列宽”提供当前列、全部列、自动铺满容器；双击表头列边界也会测量当前列。测宽以表头和当前聚合结果为准，大量行时等距抽样最多 200 行。

原生实例 API

import { PivotTable } from "@canvas-components/pivot-table";

const table = new PivotTable(container, options);
table.mount();

table.getPivotModel();
table.getVisibleRowNodes();
table.getVisibleColumnNodes();
table.selectCell(address);
table.selectNode("row", nodeId);
table.scrollToCell(address);
table.setDimensionFilter("row", "region", filter);
table.setIndicatorFilter("sales", columnPathKey, filter);
table.setDimensionSort("row", "region", "asc");
table.setIndicatorSort({
  axis: "row",
  dimensionKey: "region",
  indicatorKey: "sales",
  direction: "desc",
});
table.autoFitColumnWidths();
table.autoFitColumnWidths(undefined, true); // 测宽后铺满容器
table.getCellRecords(cellContext);
table.exportCsv({ mode: "visible" });
table.exportXlsx({ mode: "all", sheetName: "销售透视" });
table.getState();
table.restoreState(snapshot);
table.getDebugSnapshot();

table.destroy();

ReactPivotTable 的 ref 透传选择、筛选、排序、导出、状态快照和调试方法，不在 React 层复制聚合或布局逻辑。

XLSX 导出配置

右键 XLSX 导出与 ListTable 共用导出配置协议和 Worker 编码流程，支持主线程回退、进度回调及大文件拆分（默认每文件最多十万行）。通过 exportOptions 设置默认行为：

exportOptions: {
  fileName: "销售透视.xlsx",
  sheetName: "销售透视",
  promptFileName: true,
  worker: "auto",
  maxRowsPerFile: 100_000,
}

settings 可指定导出列、列顺序、数据排序、汇总配置与 includeSummary。这些设置只作用于导出副本；小计与总计不参与普通数据行排序，修改汇总方式时按对应原始记录重新计算，避免重复统计。多级表头及合并范围随列选择、顺序调整而变化。

原生 table.exportXlsx(options) 仍同步返回字节，不弹窗也不下载；UI 导出使用异步 Worker 流程。exportPivotMatrixToXlsxFile 可用于按相同流程保存自定义导出矩阵。

调试模式

传入 debug: true 会显示表头、表体、视口和当前命中单元格的调试边框。也可以按需控制覆盖层、输出绘制或状态日志，并接收布局和绘制耗时：

const table = new PivotTable(container, {
  ...options,
  debug: {
    enabled: true,
    showHeaderBounds: true,
    showBodyBounds: true,
    showViewportBounds: true,
    showHitTarget: true,
    onPerformance: (metric) => console.info(metric),
  },
});

table.getDebugSnapshot();

getDebugSnapshot() 同时返回聚合缓存指标、最近一次布局、滚动、选区、命中结果和绘制统计。

自定义聚合器

const weightedAverage = {
  create: () => ({ weightedValue: 0, weight: 0 }),
  add: (state, value, context) => {
    const weight = Number(context.record.weight ?? 0);
    state.weightedValue += Number(value ?? 0) * weight;
    state.weight += weight;
  },
  finalize: (state) =>
    state.weight === 0 ? null : state.weightedValue / state.weight,
};

const indicators = [
  {
    key: "weightedPrice",
    dataIndex: "price",
    aggregator: weightedAverage,
  },
];

聚合器状态按维度组合隔离。add 不得复用其他单元格状态；需要大数据分块时可实现 merge。

滚动条配置

scrollbar 同时适用于原生表格与 React 适配组件。通用配置由 horizontal、vertical 单独覆盖；不配置时保留原有外观。

scrollbar: {
  thickness: 10,
  thumbColor: '#8793a5',
  trackColor: '#f1f5f9',
  buttonColor: '#475569',
  thumbRadius: 4,
  horizontal: { thickness: 8, thumbColor: '#1677ff' },
  vertical: { thickness: 14, trackColor: '#e2e8f0' },
}

• thickness：横向滚动条高度、纵向滚动条宽度，单位 px，默认 10，最小 6。
• thumbColor / trackColor / buttonColor：滑块、滚动槽、两端箭头颜色。
• thumbRadius：滑块圆角，0 为直角；不传时保持胶囊形状。
• horizontal: false 或 vertical: false：单独隐藏某一轴，也可设置该轴的 visible: false。
• visible: false：同时隐藏两轴，优先于单轴设置。隐藏后释放对应槽位，仍可通过滚轮或程序滚动。

配置仅作用于当前 Canvas 表格，不修改全局浏览器滚动条样式。