QiuVision - 品味前端 · 于界面与光影之间

ECharts 不支持原生多层 X 轴。我们用 bar series 模拟出多层表头效果，但这套逻辑在 4 个图表包中各自维护、逐渐分叉——函数命名不同、参数不同、甚至 label 渲染策略也不同。本文完整记录了如何将它们收敛为一个独立的公共模块 @guwave/multi-x-axis，涵盖架构设计、类型体系、核心算法、渲染层抽象、以及各图表包的集成模式。

本文侧重模块架构与工程实现。如果你对自适应合并算法的设计思路和工程决策过程更感兴趣，可以阅读姊妹篇《ECharts 多层 X 轴智能自适应合并：从 Hack 到优雅的工程实践》。

一、为什么需要这个包

1.1 ECharts 的原生局限

ECharts 的 category axis 只支持单层类目轴。它可以通过 axisLabel.formatter 折行来做简单的分层标注，但存在本质缺陷：

每一层不是独立的可点击、可样式化实体
无法做"合并边框"的表头视觉
无法做分层独立的自适应合并

1.2 Bar Series 模拟方案

我们的做法是用若干条 描边空心 bar series 堆叠在图表下方，模拟出多层表头：

╔═══╤═══╤═══╤═══╤═══╤═══╤═══╗
║ D1│ D2│ D3│ D4│ D5│ D6│ D7║   ← Layer 0: Wafer（最内层）
╠═══╧═══╧═══╤═══╧═══╧═══╧═══╣
║   Lot1     │      Lot2     ║   ← Layer 1: Lot（最外层）
╚════════════╧═══════════════╝

每一层就是一条 bar series，每个 bar 是该层级下的一个"格子"(Cell)，白色填充 + 灰色描边 + 居中 label。

1.3 四包同源，各自漂移

在抽取公共模块之前，仓库中有 4 个图表包各自维护了独立的 multiXAxis.ts：

包	核心差异
line-chart / bar-chart	完全一致，逐字节相同
yield-trend-chart	多一个 `yAxisOffset` 参数（双 Y 轴）
box-chart	差异最大：函数命名、参数命名、返回值命名、label 渲染方式、旋转计算全部不同

详细对比：

维度	line-chart / bar-chart	yield-trend-chart	box-chart
合并函数	`mergeConsecutiveBlocks()`	同左	`extractXAxisLevels()`（无 groupKey）
yAxisIndex	`gridIndex`	`gridIndex + yAxisOffset`	`gridIndex`
label 渲染	`formatter: () => truncateText(...)`	同左	`formatter: '{b}'` + ECharts 原生截断
autoHeight	有（`isAutoHeight` + `getTextWidth`）	同左	无（固定 `levelHeight`）
grid.bottom	`0`（外部累计）	同左	内部计算 `(levelCount - i - 1 + statisticsCount) * levelHeight`
性能标记	无	无	`large: true` / `animation: false` / `emphasis: disabled`

这就是典型的「复制粘贴 → 各自演化 → 代码分叉」——是时候收敛了。

二、包结构与模块职责

packages/multi-x-axis/
├── package.json           # @guwave/multi-x-axis v0.1.0
├── src/
│   ├── index.ts           # 公共 API 出口（30 行）
│   ├── types.ts           # 统一类型定义（100 行）
│   ├── constants.ts       # 常量与默认配置（45 行）
│   ├── baseCells.ts       # 结构合并：行程编码（42 行）
│   ├── textMetrics.ts     # 文本度量 + LRU 缓存 + 截断（103 行）
│   ├── adaptiveMerge.ts   # 自适应合并核心算法（158 行）
│   ├── cellSeries.ts      # ECharts bar series 生成（120 行）
│   ├── axisConfig.ts      # 全链路编排引擎（326 行）
│   └── __tests__/
│       ├── baseCells.test.ts       (85 行)
│       ├── textMetrics.test.ts     (132 行)
│       ├── adaptiveMerge.test.ts   (192 行)
│       └── axisConfig.test.ts      (178 行)

关键的包配置：

JSON

{
  "name": "@guwave/multi-x-axis",
  "version": "0.1.0",
  "type": "module",
  "sideEffects": false,
  "peerDependencies": { "echarts": "^5.0.0" }
}

peerDependencies 不捆绑 ECharts，由宿主项目提供
sideEffects: false 支持 tree-shaking
ESM only（"type": "module"）

数据流总览

加载中...

三、类型体系：从原始数据到最终渲染

类型设计是整个模块的骨架，定义了数据在流水线中每个阶段的形态。

3.1 BaseCell —— 结构合并后的最小单元

types.ts

interface BaseCell {
  startIdx: number;     // 覆盖的原始数据点起始索引
  endIdx: number;       // 覆盖的原始数据点结束索引
  rawValue: string;     // 该组的原始值
  span: number;         // = endIdx - startIdx + 1
  pixelWidth: number;   // = span * pxPerPoint，由调用方填充
}

BaseCell 是不可变的缓存——当 resize / zoom 发生时，只需重算 pixelWidth，BaseCell 的索引和值结构不变。

3.2 DisplayCell —— 最终渲染单元

types.ts

interface DisplayCell {
  startIdx: number;
  endIdx: number;
  label: string;          // 最终显示文本（可能是范围如 "D1 ~ D5"）
  pixelWidth: number;
  isMerged: boolean;      // 是否由多个 BaseCell 合并而来
  baseCellCount: number;  // 合并了多少个 BaseCell
  rawValue: string;       // 首个 BaseCell 的原始值
  lastRawValue: string;   // 末个 BaseCell 的原始值
}

rawValue + lastRawValue 的设计让 tooltip 可以展示完整的合并范围（如 Lot1 ~ Lot5），而 label 可能已经被截断或简化。

3.3 核心入参与输出

types.ts

interface MultiXAxisBuildParams {
  xValues: string[][];            // 每个数据点的多层值，按外层→内层排列
  levelCount: number;             // 层级数
  xAxisWidth: number;             // 可绘制区域像素宽度
  gridLeft: number;
  gridRight: number;
  dataSeriesMaxGridIndex: number; // 数据系列最大 gridIndex
  xAxisLabel?: XAxisLabelConfig;
  xAxisLevelNames?: string[];
  yAxisOffset?: number;           // yield-trend-chart 传 1
  statisticsCount?: number;       // box-chart 统计行数
  adaptiveMerge?: AdaptiveMergeConfig;
}

interface MultiXAxisResult {
  grids: Record<string, any>[];
  xAxes: Record<string, any>[];
  yAxes: Record<string, any>[];
  series: Record<string, any>[];
  layers: LayerOutput[];          // 供外部使用的层结构信息
}

MultiXAxisBuildParams 中有两个关键的"差异参数"：

yAxisOffset：yield-trend-chart 有双 Y 轴（左折线 + 右柱状），多层 X 轴的 bar series 需要偏移 yAxisIndex
statisticsCount：box-chart 在多层 X 轴下方还有统计行，需要在 grid.bottom 中预留空间

3.4 自适应合并配置

types.ts

interface AdaptiveMergeConfig {
  enabled?: boolean;                    // 默认 true
  minLabelPx?: number | 'auto';        // 默认 'auto'（P90 估算）
  mergeLabelStrategy?: MergeLabelStrategy;  // 'auto' | 'range' | 'first' | 'count'
  rangeSeparator?: string;              // 默认 ' ~ '
  labelPaddingX?: number;              // 默认 8
}

'auto' 的 minLabelPx 是核心设计——它让模块能自动根据当前数据的 label 长度分布来决定合并粒度，无需手动配置。

四、baseCells —— 行程编码结构合并

结构合并是最基础的一步，本质上就是行程编码 (Run-Length Encoding)。

4.1 单层合并

baseCells.ts

function buildBaseCells(layerValues: string[]): BaseCell[] {
  const cells: BaseCell[] = [];
  let i = 0;
  while (i < layerValues.length) {
    let j = i;
    while (j + 1 < layerValues.length && layerValues[j + 1] === layerValues[i]) j++;
    cells.push({
      startIdx: i,
      endIdx: j,
      rawValue: layerValues[i],
      span: j - i + 1,
      pixelWidth: 0,
    });
    i = j + 1;
  }
  return cells;
}

单次扫描，时间复杂度 O(n)。这个函数统一了 line/bar/yield-trend 的 mergeConsecutiveBlocks 和 box-chart 的 extractXAxisLevels。

4.2 多层聚合

baseCells.ts

function buildAllLayerBaseCells(
  xValues: string[][],   // 每个数据点有多层值
  levelCount: number,
  pxPerPoint: number,    // 每个数据点占多少像素
): BaseCell[][] {
  const result: BaseCell[][] = [];
  for (let layer = 0; layer < levelCount; layer++) {
    const layerValues = xValues.map(xv => xv[layer] ?? '');
    const cells = buildBaseCells(layerValues);
    for (const c of cells) c.pixelWidth = c.span * pxPerPoint;
    result.push(cells);
  }
  return result;
}

xv[layer] ?? '' 的容错处理：当某个数据点缺少某一层的值时，用空字符串填充（仍可被行程编码合并）。

五、textMetrics —— Canvas 文本度量与 LRU 缓存

5.1 为什么需要精确度量

不同 label 的文本长度差异巨大（"W1" vs "2024-01-01 Lot-ABC-0231"），不能用字符数或 magic number 来估算。唯一靠谱的方式是 CanvasRenderingContext2D.measureText。

5.2 基于 Map 的 LRU 缓存

同一个图表在 resize / zoom 时会反复测量相同文本。我们利用 ES6 Map 的插入顺序特性实现了一个轻量 LRU 缓存：

textMetrics.ts

const LRU_CAPACITY = 1000;

class TextMetricsCache {
  private cache = new Map<string, number>();
  private canvas: HTMLCanvasElement | null = null;

  measure(text: string, fontSize = 12, fontFamily = 'sans-serif'): number {
    const key = `${fontSize}|${fontFamily}|${text}`;
    const cached = this.cache.get(key);
    if (cached !== undefined) {
      // 命中：delete + set 将 key 移到末尾（最近使用）
      this.cache.delete(key);
      this.cache.set(key, cached);
      return cached;
    }
    const width = this.rawMeasure(text, fontSize, fontFamily);
    if (this.cache.size >= LRU_CAPACITY) {
      // 淘汰：Map.keys().next() 返回最早插入的 key
      const first = this.cache.keys().next().value;
      if (first !== undefined) this.cache.delete(first);
    }
    this.cache.set(key, width);
    return width;
  }
}

Map LRU 的原理：Map 保持键的插入顺序。delete + set 实现"提升到末尾"（LRU touch），keys().next().value 获取最旧的键来淘汰。无需额外的双向链表，代码极简。

降级策略：当 getContext('2d') 失败（如 SSR 环境）时，使用 text.length * fontSize * 0.6 的等宽估算。

5.3 文本宽度估算

textMetrics.ts

function estimateLabelPx(text: string, fontSize = 12, paddingX = 8): number {
  return getTextWidth(text, fontSize) + paddingX * 2;
}

paddingX 是 label 与 cell 边框之间的留白。8px 是默认值，防止文字紧贴边框。

5.4 尾部截断（truncateText）

经典的二分搜索截断——找到最长的前缀 prefix + '…' 使其像素宽度 ≤ maxWidth：

textMetrics.ts

function truncateText(text: string, maxWidth: number, fontSize = 12): string {
  if (getTextWidth(text, fontSize) <= maxWidth) return text;
  let lo = 0, hi = text.length;
  while (lo < hi) {
    const mid = Math.ceil((lo + hi) / 2);
    if (getTextWidth(text.slice(0, mid) + '…', fontSize) <= maxWidth) lo = mid;
    else hi = mid - 1;
  }
  return lo > 0 ? text.slice(0, lo) + '…' : '…';
}

5.5 中间省略截断（truncateMiddle）

这是针对合并格范围标签设计的截断方式。传统的尾部截断 "LotABC~Lot…" 会丢失范围终点信息，中间省略保留了首尾：

1"LotABC~LotXYZ" → "LotA…tXYZ"   // 首尾都保留

textMetrics.ts

function truncateMiddle(text: string, maxWidth: number, fontSize = 12): string {
  if (getTextWidth(text, fontSize) <= maxWidth) return text;

  const ellipsis = '…';
  if (text.length <= 2 || maxWidth <= getTextWidth(ellipsis, fontSize)) {
    return truncateText(text, maxWidth, fontSize);  // 退化为尾部截断
  }

  let lo = 2, hi = text.length - 1, bestKeep = 0;
  while (lo <= hi) {
    const mid = Math.floor((lo + hi) / 2);
    const leftKeep = Math.ceil(mid / 2);
    const rightKeep = mid - leftKeep;
    const candidate = text.slice(0, leftKeep) + ellipsis + text.slice(-rightKeep);
    if (getTextWidth(candidate, fontSize) <= maxWidth) {
      bestKeep = mid;
      lo = mid + 1;
    } else {
      hi = mid - 1;
    }
  }

  if (bestKeep < 2) {
    const oneChar = text.slice(0, 1) + ellipsis;
    return getTextWidth(oneChar, fontSize) <= maxWidth ? oneChar : ellipsis;
  }

  const leftKeep = Math.ceil(bestKeep / 2);
  const rightKeep = bestKeep - leftKeep;
  return text.slice(0, leftKeep) + ellipsis + text.slice(-rightKeep);
}

算法要点：

二分搜索保留的总字符数 mid，其中约一半分给左侧、一半分给右侧
当文本极短（≤2 字符）或空间极小时退化为尾部截断
永不返回空字符串——至少返回 '…'
时间复杂度 O(log n)，配合 LRU 缓存，性能几乎无感

六、adaptiveMerge —— 密度自适应合并算法

这是整个模块的核心创新。当数据点密集时，BaseCell 的像素宽度小于 label 最小可读宽度，需要将多个 BaseCell 合并为一个 DisplayCell。

6.1 P90 分位数策略

不同 label 文本长度差异很大，固定的 minLabelPx 不可行。我们取该层所有 BaseCell label 宽度的 P90 分位数作为代表：

adaptiveMerge.ts

function resolveMinLabelPx(baseCells, config, fontSize) {
  if (typeof config.minLabelPx === 'number') return config.minLabelPx;

  const paddingX = config.labelPaddingX ?? 8;
  const widths = baseCells.map(c => estimateLabelPx(c.rawValue, fontSize, paddingX));
  widths.sort((a, b) => a - b);
  const p90Idx = Math.floor(widths.length * 0.9);
  return widths[p90Idx] ?? widths[widths.length - 1] ?? 60;
}

为什么选 P90：

策略	问题
max	被个别超长 label（如带批号的全限定名）拖累，导致过度合并
avg	约一半的 label 会显示不全
P90	兼顾多数可读性与极值容忍，10% 的超长 label 用 tooltip 和 truncateMiddle 补全

6.2 均匀分桶合并

确定 minLabelPx 后，核心计算非常简洁：

adaptiveMerge.ts

function adaptiveMergeWithinParent(baseCells, availablePx, config, fontSize) {
  const n = baseCells.length;
  if (n === 0) return [];

  const minPx = resolveMinLabelPx(baseCells, config, fontSize);
  const k = Math.max(1, Math.floor(availablePx / minPx));

  if (k >= n) {
    // 空间充裕，无需合并
    return baseCells.map(c => ({ ...c, isMerged: false }));
  }

  return mergeUniform(baseCells, k, availablePx, config, fontSize);
}

均匀分桶的关键在于 floor(i*n/k) 的整数数学：

adaptiveMerge.ts

function mergeUniform(baseCells, k, _availablePx, config, fontSize) {
  const n = baseCells.length;
  const buckets = [];

  for (let i = 0; i < k; i++) {
    const from = Math.floor((i * n) / k);
    const to   = Math.floor(((i + 1) * n) / k) - 1;

    // from ~ to 范围内的 BaseCell 合并为一个 DisplayCell
    let totalPx = 0;
    for (let j = from; j <= to; j++) totalPx += baseCells[j].pixelWidth;

    buckets.push({
      startIdx: baseCells[from].startIdx,
      endIdx: baseCells[to].endIdx,
      label: formatMergedLabel(baseCells[from].rawValue, baseCells[to].rawValue, totalPx, config, fontSize),
      pixelWidth: totalPx,
      isMerged: to > from,
      baseCellCount: to - from + 1,
      rawValue: baseCells[from].rawValue,
      lastRawValue: baseCells[to].rawValue,
    });
  }
  return buckets;
}

为什么用 floor(i*n/k) 而不是 ceil(n/k)？

当 n 不能被 k 整除时：

floor(i*n/k) 的桶大小差异 ≤ 1（如 n=10, k=3 → 3, 3, 4），视觉最均匀
ceil(n/k) 会出现"前面都是大桶、最后一个小尾巴"（如 → 4, 4, 2），观感差

这是一个经典的整数均分问题，在操作系统的负载均衡、并行计算的任务分配中也常见。

6.3 Label 生成的渐进式降级

合并发生后，一个 DisplayCell 代表一个区间。label 的生成采用 auto 策略的渐进降级：

adaptiveMerge.ts

function formatMergedLabel(firstValue, lastValue, availablePx, config, fontSize) {
  const strategy = config.mergeLabelStrategy ?? 'auto';
  const sep = config.rangeSeparator ?? ' ~ ';

  if (firstValue === lastValue) return firstValue;

  if (strategy === 'first') return firstValue;
  if (strategy === 'count') return lastValue;
  if (strategy === 'range') return `${firstValue}${sep}${lastValue}`;

  // auto 策略
  const rangeText = `${firstValue}${sep}${lastValue}`;   // "D1 ~ D5"
  if (estimateLabelPx(rangeText, fontSize) <= availablePx) return rangeText;

  const compactRange = `${firstValue}~${lastValue}`;       // "D1~D5"
  if (estimateLabelPx(compactRange, fontSize) <= availablePx) return compactRange;

  return compactRange;  // 返回紧凑形式，由 cellSeries 的 truncateMiddle 做最终截断
}

降级链路：

加载中...

每一步都保证永不返回空字符串。

6.4 分层处理：父边界隔离

这是算法中最关键的约束——内层的合并必须限制在外层 DisplayCell 的边界内。

如果不做隔离，可能出现"Day30 和 Day1 合并到同一格"跨越了月份边界的语义错误。

adaptiveMerge.ts

function buildAdaptiveDisplayCells(allBaseCells, levelCount, chartPixelWidth, config, fontSize) {
  const outputs = new Array(levelCount);

  // 最外层：父 = 整张图
  outputs[0] = adaptiveMergeWithinParent(
    allBaseCells[0], chartPixelWidth, config, fontSize,
  );

  // 内层：受上一层 DisplayCell 约束
  for (let L = 1; L < levelCount; L++) {
    const cells = [];
    for (const parent of outputs[L - 1]) {
      // 只取完全落在 parent 范围内的子 BaseCell
      const childBase = allBaseCells[L].filter(
        c => c.startIdx >= parent.startIdx && c.endIdx <= parent.endIdx,
      );
      // 以 parent 的像素宽度作为可用空间
      cells.push(...adaptiveMergeWithinParent(childBase, parent.pixelWidth, config, fontSize));
    }
    outputs[L] = cells;
  }
  return outputs;
}

每一层独立做密度自适应，但绝不跨越父边界——层级语义始终正确。

七、cellSeries —— ECharts Bar Series 的统一抽象

cellSeries.ts 将一个 DisplayCell 转化为一个 ECharts bar series 配置对象。它统一了四个图表包的所有差异。

7.1 统一的 API

cellSeries.ts

function buildMultiXCellSeries(params: {
  dataName: string;
  tooltipText: string;
  barWidth: number;       // 占比，如 0.3 = 30%
  gridIndex: number;
  yAxisOffset?: number;   // yield-trend-chart 传 1
  xAxisLabel?: XAxisLabelConfig;
  xAxisWidth: number;
  displayLabel?: string;  // 自适应合并后的显示文本
  isMerged?: boolean;
}): Record<string, any>

7.2 旋转 Label 的三角几何

当 label 需要旋转时，可用于显示文字的有效宽度会变化。我们采用了精确的三角函数计算：

cellSeries.ts

function computeValidLabelWidth(realLabelWidth, realLabelHeight, rotate, fontSize, autoHeight) {
  const absRotate = Math.abs(rotate);

  if (absRotate === 90) {
    // 90° 旋转：文本沿纵向，有效宽度取决于高度
    return autoHeight === 'auto'
      ? Math.min(realLabelWidth + fontSize, MAX_ROTA_90_HEIGHT)
      : realLabelHeight;
  }

  if (absRotate === 0) return realLabelWidth;  // 无旋转

  // 一般角度：旋转矩形内接问题
  const rad = (rotate / 180) * Math.PI;
  return Math.min(
    realLabelWidth / Math.abs(Math.cos(rad)),
    realLabelHeight / Math.abs(Math.sin(rad)),
  ) - fontSize;
}

几何原理：一个旋转了 θ 角的矩形文本，要完整放入 w × h 的容器中，文本长度不能超过 min(w/|cosθ|, h/|sinθ|)。

7.3 双重截断保险

cellSeries.ts

const truncateWidth = Math.max(0, validLabelWidth - LABEL_WIDTH_BUFFER);
const finalText = truncateMiddle(rawText, truncateWidth, fontSize);

return {
  type: 'bar',
  label: {
    formatter: () => finalText,   // 第一道：Canvas 预截断
    overflow: 'truncate',         // 第二道：ECharts 兜底
    ellipsis: '…',
  },
  // ...
};

LABEL_WIDTH_BUFFER（4px）弥补 Canvas measureText 与 ECharts 渲染引擎之间的微小测量偏差。

7.4 性能优化标记

所有 cell series 统一启用：

TypeScript

{
  large: true,                    // 大数据量优化渲染路径
  animation: false,               // 装饰性元素不需要动画
  emphasis: { disabled: true },   // 禁用鼠标悬浮高亮
}

7.5 统一的视觉样式

constants.ts

const MULTI_X_CELL_STYLE = {
  z: 299,                         // 高 z 值保证绘制在数据系列上方
  itemStyle: {
    color: '#fff',                // 白色填充
    borderColor: '#c5c5c5',       // 灰色描边
    borderWidth: 0.5,
  },
};

八、axisConfig —— 全链路编排引擎

axisConfig.ts 是整个模块中最大的文件（326 行），它编排了从数据输入到 ECharts 配置输出的完整流程。

8.1 buildMultiXAxisConfig —— 初始构建

核心逻辑分为"自适应路径"和"非自适应路径"两条分支：

axisConfig.ts

function buildMultiXAxisConfig(params: MultiXAxisBuildParams): MultiXAxisResult {
  const { xValues, levelCount, xAxisWidth, adaptiveMerge, ... } = params;
  const pxPerPoint = totalPoints > 0 ? xAxisWidth / totalPoints : 0;
  const resolvedConfig = resolveAdaptiveMergeConfig(adaptiveMerge);

  if (resolvedConfig.enabled) {
    // 自适应路径：全量构建 BaseCells + DisplayCells
    const allBaseCells = buildAllLayerBaseCells(xValues, levelCount, pxPerPoint);
    const allDisplayCells = buildAdaptiveDisplayCells(
      allBaseCells, levelCount, xAxisWidth, resolvedConfig, fontSize,
    );
    // ... 遍历 DisplayCells 生成 series
  } else {
    // 非自适应路径：仅结构合并 + MAX_MULTI_X_CELLS 安全阀
    // ... 超过 1000 cell 时显示占位提示 "Zoom in to display ..."
  }

  // 为每一层生成 grid + hidden xAxis + hidden yAxis
  return { grids, xAxes, yAxes, series, layers };
}

自适应路径 中每个 DisplayCell 的 barWidth 按比例计算：

axisConfig.ts

const cellBarWidth = (cell.endIdx - cell.startIdx + 1) / totalPoints;

一个跨越 5 个数据点的合并格，barWidth 就是 5/n（占图表宽度的 5/n）。

安全阀机制（非自适应路径）：当 BaseCell 数量超过 MAX_MULTI_X_CELLS（1000）时，整层退化为一个占满全宽的占位 bar，显示 "Zoom in to display {levelName}"，避免生成数千个 bar series 导致渲染卡死。

8.2 grid / axis 的生成策略

每一层多层 X 轴需要一组独立的 grid + xAxis + yAxis：

axisConfig.ts

// grid：高度由 label 配置决定
grids.push({
  height: singleLevelHeight,
  bottom: statisticsCount > 0
    ? (levelCount - layer - 1 + statisticsCount) * singleLevelHeight
    : 0,
  left: gridLeft,
  right: gridRight,
});

// 隐藏的 category xAxis 用于定位 bar
xAxes.push({
  type: 'category',
  gridIndex: layerGridIndex,
  axisLine: { show: false },
  axisLabel: { show: false },
  axisTick: { show: false },
});

// 隐藏的 value yAxis，让 bar 能以 value=1 绘制
yAxes.push({
  type: 'value',
  gridIndex: layerGridIndex,
  axisLine: { show: false },
  axisLabel: { show: false },
  axisTick: { show: false },
  splitLine: { show: false },
});

gridIndex 从 dataSeriesMaxGridIndex 开始：数据系列（折线、柱状、箱图等）使用 gridIndex 0，多层 X 轴从 1 开始（或更高）。

grid.bottom 的分歧统一：

line/bar/yield-trend 传 bottom: 0，由外部组件自行累计
box-chart 传 statisticsCount > 0 时内部计算 (levelCount - layer - 1 + statisticsCount) * height

8.3 rebuildMultiXSeriesOnZoom —— 缩放重建

用户拖动 dataZoom 时，只需重建 series（grid / axis 结构不变）：

axisConfig.ts

function rebuildMultiXSeriesOnZoom(params: {
  xValues: string[][];
  levelCount: number;
  xAxisWidth: number;
  dataSeriesMaxGridIndex: number;
  xAxisLabel?: XAxisLabelConfig;
  xAxisLevelNames?: string[];
  yAxisOffset?: number;
  adaptiveMerge?: AdaptiveMergeConfig;
}): Record<string, any>[]

内部走相同的自适应 / 非自适应分支逻辑，但只返回 series[]，不包含 grids / axes。

8.4 配置合并策略

axisConfig.ts

function resolveAdaptiveMergeConfig(adaptiveMerge?: AdaptiveMergeConfig) {
  return {
    ...DEFAULT_ADAPTIVE_MERGE,  // { enabled: true, minLabelPx: 'auto', ... }
    ...(adaptiveMerge ?? {}),
  };
}

用户可以只覆盖想修改的字段，其余使用默认值。

九、四个图表包的集成模式

9.1 通用集成模式

四个图表包遵循统一的三步集成：

加载中...

Series 替换策略——replaceMerge：

集成示例

// 记录多层 X 轴 series 的起始索引
const multiXSeriesStartIndex = seriesAll.length + markLineSeries.length;

// zoom 时：保留数据 series，替换多层 X 轴 series
const dataSeries = currentOption.series.slice(0, multiXSeriesStartIndex);
chart.setOption(
  { series: [...dataSeries, ...newMultiXSeries] },
  { replaceMerge: ['series'] },
);

replaceMerge: ['series'] 让 ECharts 替换整个 series 数组，而不是按索引合并（后者会在 series 长度变化时出错）。

9.2 各包差异对比

关注点	line-chart / bar-chart	yield-trend-chart	box-chart
`yAxisOffset`	默认 0	1（双 Y 轴）	默认 0
`statisticsCount`	默认 0	默认 0	`statistics.length`
zoom 时 `xAxisWidth`	`width - gridLeft - gridRight`（props）	`getCurrentXAxisWidth(option)` 从实时 grid 读取	props
dataZoom 来源	`dataZoom[0]`	`dataZoom.find(xAxisIndex === 0)`	`dataZoom[0]`
zoom 额外操作	无	无	重建统计行 + 散点 jitter
`dataSeriesMaxGridIndex`	1	1	1

9.3 yield-trend-chart 的特殊处理

yield-trend-chart 有双 Y 轴（左轴折线代表良率，右轴柱状代表数量），因此多层 X 轴的 bar series 的 yAxisIndex 需要偏移 1。

此外，它在 zoom 时从 ECharts 实时 option 中读取 grid 宽度，因为 Y 轴 label 的自适应宽度（adjustGridLeftByYLabels）可能在 setOption 后改变了 grid 边距：

YieldTrendChart.tsx

const getCurrentXAxisWidth = useCallback((option?: any) => {
  const mainGrid = option?.grid?.[0];
  const currentGridLeft = typeof mainGrid?.left === 'number' ? mainGrid.left : gridLeft;
  const currentGridRight = typeof mainGrid?.right === 'number' ? mainGrid.right : gridRight;
  return width - currentGridLeft - currentGridRight;
}, [gridLeft, gridRight, width]);

它还使用 dataZoom.find(xAxisIndex === 0) 而非 dataZoom[0]，因为 yield-trend 可以同时有 X + 左 Y + 右 Y 三个 dataZoom 组件。

9.4 box-chart 的特殊处理

box-chart 在多层 X 轴下方还有统计行（显示 boxplot 的统计值），因此：

传 statisticsCount 让多层 X 轴在 grid.bottom 中预留空间
zoom 时除了重建多层 X 轴，还要调用 rebuildStatisticsOnZoom 重建统计行
还需要重算散点图的 jitter 偏移量（因为 bar 宽度变了）

box-chart 也是唯一需要额外 re-export MULTI_X_CELL_STYLE 常量的包（统计行的 cell 需要相同样式）。

9.5 公共 API 的 Re-export

每个图表包都从 @guwave/multi-x-axis re-export 核心 API，保证下游应用可以直接从图表包引入多层 X 轴的能力：

index.ts（各图表包）

export { buildMultiXAxisConfig, rebuildMultiXSeriesOnZoom, buildMultiXCellSeries } from '@guwave/multi-x-axis';
export { getTextWidth, truncateText } from '@guwave/multi-x-axis';
export type { AdaptiveMergeConfig, XAxisLabelConfig } from '@guwave/multi-x-axis';

十、测试策略

10.1 分层单测

测试按模块分层，每一层只关注自己的职责：

模块	测试文件	核心测试点
`baseCells`	85 行	空数组 / 单值 / 全同 / 全异 / 交替 / 多层 pixelWidth
`textMetrics`	132 行	LRU 命中 / 未命中 / invalidate / 截断边界 / 中间截断
`adaptiveMerge`	192 行	k≥n / k=1 / 不整除均分 / 4 种 label 策略 / 父边界隔离
`axisConfig`	178 行	默认开启 / gridIndex 偏移 / yAxisOffset / statisticsCount / 空数据 / zoom

10.2 Canvas 环境 Mock

所有涉及文本度量的测试统一使用 vi.stubGlobal mock Canvas：

测试 Mock

vi.stubGlobal('document', {
  createElement: vi.fn(() => ({
    getContext: vi.fn(() => ({
      font: '',
      measureText: vi.fn((text: string) => ({ width: text.length * 7 })),
    })),
  })),
});

text.length * 7 提供了确定性的宽度计算，让测试结果稳定可预测。

10.3 关键测试用例

父边界隔离测试——这是自适应合并最关键的测试：

adaptiveMerge.test.ts

it('父边界隔离', () => {
  // 外层 2 个 BaseCell：[0,1] 和 [2,3]
  // 内层 4 个 BaseCell：[0], [1], [2], [3]
  // 验证：内层合并不会跨越外层的 [0,1] | [2,3] 边界
  const result = buildAdaptiveDisplayCells(allBaseCells, 2, chartWidth, config, 12);
  // 内层的前两个 cell 索引 ∈ [0,1]，后两个 ∈ [2,3]
});

自适应 vs 非自适应对比——验证默认行为：

axisConfig.test.ts

it('不传 adaptiveMerge 时默认启用', () => {
  const adaptive = buildMultiXAxisConfig(narrowParams);
  const structural = buildMultiXAxisConfig({ ...narrowParams, adaptiveMerge: { enabled: false } });
  expect(adaptive.series.length).toBeLessThan(structural.series.length);
});

10.4 测试设计原则

纯 TS 模块测试：不依赖 React 或 ECharts 运行时
确定性 Mock：Canvas 宽度 = 字符数 × 固定系数，结果可预测
A/B 对比：用 enabled: true vs enabled: false 对比验证合并效果
边界覆盖：空数组、单元素、k=1、n 不被 k 整除、首尾同值等

十一、常量与默认配置

constants.ts

const MULTI_X_LEVEL_HEIGHT = 24;    // 每层默认高度 (px)
const MAX_MULTI_X_CELLS = 1000;     // 非自适应模式的安全阀
const MAX_ROTA_90_HEIGHT = 120;     // 90° 旋转时最大高度限制
const LABEL_WIDTH_BUFFER = 4;       // 截断计算的像素余量

const DEFAULT_ADAPTIVE_MERGE = {
  enabled: true,                    // 默认开启
  minLabelPx: 'auto',              // P90 自动估算
  mergeLabelStrategy: 'auto',      // 渐进降级
  rangeSeparator: ' ~ ',
  labelPaddingX: 8,
};

const MULTI_X_CELL_STYLE = {
  z: 299,                           // 高 z 值
  itemStyle: {
    color: '#fff',                  // 白色填充
    borderColor: '#c5c5c5',         // 灰色描边
    borderWidth: 0.5,
  },
};

所有常量都有明确的语义命名，避免 magic number。

十二、公共 API 总览

index.ts

// ── 核心 API ──
export { buildMultiXAxisConfig } from './axisConfig';      // 初始构建
export { rebuildMultiXSeriesOnZoom } from './axisConfig';   // 缩放重建
export { buildMultiXCellSeries } from './cellSeries';       // 单个 cell series
export { buildBaseCells, buildAllLayerBaseCells } from './baseCells';
export { buildAdaptiveDisplayCells, adaptiveMergeWithinParent } from './adaptiveMerge';

// ── 文本度量 ──
export { getTextWidth, truncateText, truncateMiddle, estimateLabelPx, textMetrics } from './textMetrics';

// ── 类型 ──
export type { XAxisLabelConfig, BaseCell, DisplayCell, LayerOutput,
             MultiXAxisBuildParams, MultiXAxisResult,
             AdaptiveMergeConfig, MergeLabelStrategy } from './types';

// ── 常量 ──
export { MULTI_X_LEVEL_HEIGHT, DEFAULT_X_AXIS_LABEL, DEFAULT_ADAPTIVE_MERGE,
         MULTI_X_CELL_STYLE, MAX_MULTI_X_CELLS } from './constants';

API 分为四组：

核心 API：初始构建和缩放重建，99% 的场景只需要这两个
底层算法：buildBaseCells、adaptiveMergeWithinParent 等，供高级用户直接操控
文本度量：通用工具，图表组件可能在多层 X 轴之外也需要
常量：样式和限制值，保证各包视觉一致

十三、工程经验与设计决策

13.1 "先收敛，再增强" 的重构策略

我们没有在四个包中各自加自适应合并（那样差异会进一步放大），而是先把四包的共同逻辑抽成公共模块、确保行为不变，然后在公共模块上统一加增量能力。

13.2 向后兼容的配置设计

TypeScript

// 不传 adaptiveMerge → 默认启用自适应
buildMultiXAxisConfig({ xValues, levelCount, ... });

// 显式关闭 → 行为与旧版完全一致
buildMultiXAxisConfig({ ..., adaptiveMerge: { enabled: false } });

默认值在 DEFAULT_ADAPTIVE_MERGE 中集中管理，用户只覆盖想改的字段。

13.3 像素驱动而非数量驱动

合并触发条件是"像素宽度不足"，不是"数据超过 N 条"。同样 1000 个数据点，在 1600px 的大屏上可能不需要合并，在 400px 的侧边栏面板则需要大量合并。像素驱动天然适配不同分辨率和容器尺寸。

13.4 分层独立 + 父边界隔离

每一层独立决策合并粒度，但内层合并绝不跨越外层边界。这是整个算法正确性的基石。

13.5 多级防御

文本显示有三级防御：

formatMergedLabel：自动选择 range / compact / first 格式
truncateMiddle：保留首尾的中间省略截断
ECharts overflow: 'truncate'：渲染层兜底

加上 LABEL_WIDTH_BUFFER 的 4px 余量，确保 Canvas 和 ECharts 的微小测量偏差不会导致 label 溢出。

13.6 性能考量

措施	收益
LRU 缓存（容量 1000）	避免重复 measureText 调用
`large: true` + `animation: false`	ECharts 走大数据量优化渲染路径
`emphasis: { disabled: true }`	禁用装饰 bar 的悬浮重绘
二分搜索截断	O(log n) 替代 O(n) 逐字裁剪
仅重建 series（zoom 时）	grid / axis 结构不变，避免全量重建
`sideEffects: false`	未使用的导出可被 tree-shake

13.7 复杂度分析

步骤	复杂度
结构合并	O(n × L)，n = 数据点数，L = 层数
P90 计算	O(m × log m)，m = BaseCell 数（排序）
自适应合并	O(m × L)
Label 截断	O(m × log t)，t = 文本长度
LRU 查找	O(1) 均摊

实测：1000 数据点 × 4 层，buildAdaptiveDisplayCells < 8ms。

附录：快速上手

最简使用

import { buildMultiXAxisConfig } from '@guwave/multi-x-axis';

const result = buildMultiXAxisConfig({
  xValues: data.points.map(p => p.xValues),
  levelCount: 2,
  xAxisWidth: 800,
  gridLeft: 60,
  gridRight: 20,
  dataSeriesMaxGridIndex: 1,
});

chart.setOption({
  grid: [mainGrid, ...result.grids],
  xAxis: [mainXAxis, ...result.xAxes],
  yAxis: [mainYAxis, ...result.yAxes],
  series: [...dataSeries, ...result.series],
});

缩放响应

import { rebuildMultiXSeriesOnZoom } from '@guwave/multi-x-axis';

chart.on('datazoom', () => {
  const slicedXValues = /* 根据 zoom 范围切片 */;
  const newSeries = rebuildMultiXSeriesOnZoom({
    xValues: slicedXValues,
    levelCount: 2,
    xAxisWidth: currentXAxisWidth,
    dataSeriesMaxGridIndex: 1,
  });
  chart.setOption(
    { series: [...dataSeries, ...newSeries] },
    { replaceMerge: ['series'] },
  );
});

自定义合并策略

自定义配置

buildMultiXAxisConfig({
  // ...
  adaptiveMerge: {
    enabled: true,
    minLabelPx: 'auto',           // 或固定像素值如 80
    mergeLabelStrategy: 'range',   // 'auto' | 'range' | 'first' | 'count'
    rangeSeparator: ' → ',
    labelPaddingX: 12,
  },
});

写在最后

@guwave/multi-x-axis 的诞生过程体现了一个工程实践原则：先收敛，再增强。

面对四份各自漂移的 multiXAxis.ts，我们没有选择在每个包中独立修补，而是先花时间对齐差异、抽取公共模块、建立统一的类型体系和测试覆盖，然后才在稳固的基础上增加自适应合并这样的增量能力。这个决策让后续的 bug 修复和功能迭代只需要改一个地方，四个图表包同步受益。

整个模块的设计也刻意保持了最小 API 面积：99% 的场景只需要 buildMultiXAxisConfig 和 rebuildMultiXSeriesOnZoom 两个函数。底层的 buildBaseCells、adaptiveMergeWithinParent 等暴露给高级用户，但不是默认路径。这种"简单的事情简单做、复杂的事情留出口"的分层设计，是组件库和工具库追求的理想状态。

关于自适应合并算法的设计思路、P90 策略、均匀分桶、渐进式降级等工程决策的深入分析，请参阅《ECharts 多层 X 轴智能自适应合并：从 Hack 到优雅的工程实践》。

@guwave/multi-x-axis：ECharts 多层 X 轴公共模块的设计与实现@guwave/multi-x-axis：ECharts 多层 X 轴公共模块的设计与实现

一、为什么需要这个包

1.1 ECharts 的原生局限

1.2 Bar Series 模拟方案

1.3 四包同源，各自漂移

二、包结构与模块职责

数据流总览

三、类型体系：从原始数据到最终渲染

3.1 BaseCell —— 结构合并后的最小单元

3.2 DisplayCell —— 最终渲染单元

3.3 核心入参与输出

3.4 自适应合并配置

四、baseCells —— 行程编码结构合并

4.1 单层合并

4.2 多层聚合

五、textMetrics —— Canvas 文本度量与 LRU 缓存

5.1 为什么需要精确度量

5.2 基于 Map 的 LRU 缓存

5.3 文本宽度估算

5.4 尾部截断（truncateText）

5.5 中间省略截断（truncateMiddle）

六、adaptiveMerge —— 密度自适应合并算法

6.1 P90 分位数策略

6.2 均匀分桶合并

6.3 Label 生成的渐进式降级

6.4 分层处理：父边界隔离

七、cellSeries —— ECharts Bar Series 的统一抽象

7.1 统一的 API

7.2 旋转 Label 的三角几何

7.3 双重截断保险

7.4 性能优化标记

7.5 统一的视觉样式

八、axisConfig —— 全链路编排引擎

8.1 buildMultiXAxisConfig —— 初始构建

8.2 grid / axis 的生成策略

8.3 rebuildMultiXSeriesOnZoom —— 缩放重建

8.4 配置合并策略

九、四个图表包的集成模式

9.1 通用集成模式

9.2 各包差异对比

9.3 yield-trend-chart 的特殊处理

9.4 box-chart 的特殊处理

9.5 公共 API 的 Re-export

十、测试策略

10.1 分层单测

10.2 Canvas 环境 Mock

10.3 关键测试用例

10.4 测试设计原则

十一、常量与默认配置

十二、公共 API 总览

十三、工程经验与设计决策

13.1 "先收敛，再增强" 的重构策略

13.2 向后兼容的配置设计

13.3 像素驱动而非数量驱动

13.4 分层独立 + 父边界隔离

13.5 多级防御

13.6 性能考量

13.7 复杂度分析

附录：快速上手

最简使用

缩放响应

自定义合并策略

写在最后

评论

@guwave/multi-x-axis：ECharts 多层 X 轴公共模块的设计与实现