@canvas-components/pivot-table

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

能力

• 双轴多级维度树与稳定节点 ID
• sum、avg、count、distinctCount、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 是透视维度额外支持的展开配置。

过滤发生在聚合前。filters、sorts、selection 和 expandedRowKeys/expandedColumnKeys 可受控；不传时由实例维护。

原生实例 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.setDimensionSort("row", "region", "asc");
table.setIndicatorSort({
  axis: "row",
  dimensionKey: "region",
  indicatorKey: "sales",
  direction: "desc",
});
table.getCellRecords(cellContext);
table.exportCsv({ mode: "visible" });
table.exportXlsx({ mode: "all", sheetName: "销售透视" });
table.getState();
table.restoreState(snapshot);
table.getDebugSnapshot();

table.destroy();

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

调试模式

传入 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 表格，不修改全局浏览器滚动条样式。