pivot table · model + canvas

把多维数据
折叠成一张二维表

聚合给出每个维度组合唯一的数据;矩阵变换把维度序号映射成 [x, y];Canvas 只绘制视口内的单元格。模型、布局和渲染彼此独立。

  • 零依赖
  • 矩阵布局
  • 视口虚拟化
  • 多层表头
  • ES Modules
核心模块
2
运行时依赖
0
绘制成本
O(可见格)
压测网格
150×150

02 · pipeline

一条核心数据流,一组扩展挂载点

聚合、布局、几何、渲染各自独立;内置 / 示例 feature 挂在阶段之间或渲染之后, 新增能力也复用同一组挂载点。

核心阶段 内置 / 示例 feature 可挂载扩展点
  1. 01

    明细 rows

    输入

    业务明细,尚未聚合。每一行是一条原始记录。

    rows[]rows[]
    挂载点 过滤 / 排序· 预处理(规划中)
  2. 02

    aggregate

    聚合

    按维度 key 分组,每个维度组合只保留一行,计算 count / sum / avg / min / max。

    rows[]cube.rows[]
    挂载点 dual-measure· combineMeasures() 自定义度量 / 上卷· 派生 cube
  3. 03

    layoutPivot

    布局

    把成员取值编码成序号,通过仿射矩阵得到整数网格坐标,并生成可递归渲染的表头。

    cube.rows[]layout
    挂载点 totals· rollupTotals(cube) + withTotals(layout) collapse· collapseCube() + 表头交互 展示布局派生· 排序 / 合并 / 自定义派生
  4. 04

    computePivotGeometry

    几何

    根据视口和滚动偏移计算屏幕矩形、可见范围与裁剪区;不接触 Canvas。

    layoutgeometry
    挂载点 viewport / overscan· 表头尺寸
  5. 05

    renderPivot

    渲染

    绘制背景、网格线、文本和冻结表头;只遍历视口内的格子。

    layout + geometryCanvas
    挂载点 heatmap· cellStyle overlay· renderWithOverlay() scrollbar· 渲染后叠加 + 自动隐藏 cell-marker· 示例 feature(cellStyle + overlay) formatValue / theme· 渲染配置
交互回路 scrollX / scrollY 变化 → 重新计算几何 → 重绘 命中测试 / 折叠 / 下钻 → 重入 collapseCube、aggregate 或 layoutPivot
核心不依赖 feature。 依赖方向始终是 site / features → model / render;feature 只读取核心输出, 通过上面的挂载点扩展。架构守卫测试会阻止核心反向 import features。

03 · matrix transform

一次矩阵乘法,定位每个单元格

维度层级等价于混合进制数:父级粗定位,子级在父级划出的块内细定位。 整棵树最终折叠成一个固定矩阵。

一条记录被编码成增广向量,每个维度贡献一个成员序号 id,最后补一个常数项 1:

v = [i₁, i₂, ..., i_D, 1]ᵀ

矩阵 M 的第 d 列是该维度所在轴的单位向量乘以 spand,最后一列是平移:

[x, y]ᵀ = M · v

父子 span 满足乘积关系。父维度每变一级,跨过的行数正好是 子维度成员数乘以子维度 span:

span_parent = n_child × span_child
span_d      = Π n_c(c 为 d 的后代)

cartesian 默认

每个父成员下补齐全局子成员,形成规则网格。span 与父成员无关, 整个布局是一个固定矩阵,代价是空单元格。

compact 紧凑

只排列数据中实际出现的组合,父成员块大小可变。没有全局固定矩阵, 但每条记录仍给出分段仿射变换。

  • 表头成员的 offset / size 直接对应 rowspan / colspan。
  • 重复维度组合默认报错,强制先聚合,不在布局层偷偷合并。
  • 每个轴支持一条层级链:单根、每个父维度最多一个子维度。

04 · live demo

滚动一张真实数据透视表

5 个区域、20 个城市、6 年、3 类产品,共 867 条明细聚合为 288 行。 表头冻结,数据区只绘制视口内的部分。

加载中…
Demo 扩展位
开启后点击行/列父表头折叠;可与行/列汇总、并列度量同时使用;cartesian 不可用

滚轮或拖拽平移,拖动右侧 / 底部滚动条可精确跳转;滚动条在停止操作后 自动隐藏,悬停或拖动时保持显示;Shift + 滚轮横向滚动;聚焦画布 后可用方向键、PageUp / PageDown、Home / End。并列度量时,热力图和行/列汇总都按 measure 分列。角区标签 开关演示自定义叠加层;高值标记演示自定义 feature:cellStyle 改底色, renderWithOverlay 画角标;折叠模式开启后可点击行/列父表头折叠, 可与行/列汇总、并列度量同时使用;cartesian 暂不可用。行/列小计与总计 分别在 region、year 维度末尾插入汇总。

05 · performance

成本跟视口走,而不是跟整张表走

滚动时只遍历可见单元格;表头按 offset 二分剪枝;尺寸不变时复用 canvas 缓冲区;热力范围按 layout 缓存。

22,500 150×150 压测网格的总格数
50 480×280 数据视口实际绘制格数
1 次 每个 layout 只扫描一次热力范围

渲染层做了什么

  • 视口虚拟化:只遍历 visible 范围,总格数不参与每帧循环。
  • 单元格查找 O(1):模型输出 cellMap。
  • 网格线合并为一次 beginPath() + stroke()。
  • 表头 offset 单调,二分跳过视口外成员及其子树。
  • 数据区与两块表头分别裁剪,冻结表头不触发整表重绘。
  • DPR 变换只设置一次;尺寸不变不重置 canvas 缓冲区。

方案取舍

  • Canvas 2D · 当前 约 1k–100k 格;零依赖,文本与矩形批量绘制快。
  • Canvas + 离屏缓存 连续滚动的大表;缓存表头、网格和斑马纹位图。
  • WebGL / WebGPU 十万到百万格、平滑缩放;文本排版和命中测试成本更高。
  • DOM / SVG 小表、文本选择、屏幕阅读器;节点多时性能下降明显。
阅读完整渲染管线与性能方案

06 · benchmark

本机实测:一万到一千万条明细

用真实的 aggregate + layoutPivot 跑模型变换,每个规模独立 Node 进程重复 3 次, 取总耗时中位数。千万级在本机可用内存不足,改用分片聚合;表格里明确标注两种方式。

— 100 万条 · 单次变换
— 1000 万条 · 分片变换
— 单次百万级峰值内存
原始记录 生成 聚合 合并 布局 变换 峰值内存 方式
正在加载基准结果…

基准数据来自 bench/results.json;页面需要通过 HTTP 打开。

怎么测的

  • 加载中…

读数

  • 聚合是主要成本 明细数每增一个数量级,聚合耗时大致同向增长;单次样本会受 GC 与宿主负载影响。
  • 布局几乎恒定 固定 1536 个维度组合后,布局耗时基本不变,与原始明细数无关。
  • 千万级靠分片控制内存 单次百万级已需要约 250 MB;分片千万级把峰值控制在两百 MB 以内。

结果文件: bench/results.json · 复现:node bench/run.mjs · 脚本: bench/transform.mjs

07 · depth sweep

维度越深,矩阵变换要多久?

固定 100 万条明细,先加行维度、再加列维度,每层 2 个成员。 停止条件看矩阵变换(layoutPivot)是否超过 3 秒,同时记录聚合耗时和峰值内存。

— 完成到 · 行深 / 列深
— 最后一步 · 矩阵变换
— 最后一步 · 峰值内存

正在加载深度实验结果…

先增加行维度(列深 0)

行深 列深 聚合 矩阵变换 合计 峰值内存 输出
正在加载…

再增加列维度(行深 10)

行深 列深 聚合 矩阵变换 合计 峰值内存 输出
正在加载…

怎么测的

  • 加载中…

读数

  • 行深度主要增加聚合成本 本次测量中,行阶段网格最大只有 1,024 格,矩阵变换 1.9–25.9 ms;主要时间花在 100 万条明细分组上。
  • 列深度让网格翻倍 本次测量中,行网格固定 1,024,列每加一层翻倍;矩阵变换从 75 ms 增长到 2.74 s。
  • 内存先到达上限 列深 7 峰值 744.8 MB;列深 8 在 768 MB 堆上 OOM,未完成,因此 3 秒阈值没有被测到。

实验数据来自 bench/depth-results.json;页面需要通过 HTTP 打开。

结果文件: bench/depth-results.json · 复现:node bench/depth-run.mjs · 脚本: bench/depth-run.mjs

08 · quickstart

直接使用

没有构建步骤,没有运行时依赖。下面按 Demo 功能提供最小调用片段,可直接复制。

本地运行

node examples/demo.mjs
node --test test/model/*.test.mjs test/render/*.test.mjs \
  test/features/*.test.mjs test/site/*.test.mjs

浏览器示例需要通过 HTTP 打开,ES module 不能走 file://。

python3 -m http.server 8000
# http://localhost:8000/

自定义 feature

核心不依赖 feature;选一个挂载点,写只读核心输出的函数。

  1. 选挂载点 数据派生、布局派生、渲染配置或渲染后叠加。
  2. 写 createXxx() 返回 cellStyle、draw 或新的展示布局。
  3. 传给核心 renderPivot / renderWithOverlay,不修改核心。

挂载点文档