Apache ECharts 中 boxplot 图表 encode 配置失效问题解析

问题背景

在 Apache ECharts 5.5.1 版本中，开发者发现当使用 boxplot（箱线图）图表时，如果直接在 series.data 中指定数据并配合 encode 配置项使用时，会出现编码规则被忽略的情况。具体表现为：

1. 当 x 轴为类别轴时，图表会默认使用前5个可用维度，而忽略 encode 中指定的规则
2. 坐标轴显示的是数字索引而非预期的类别值
3. 同样的数据如果通过 dataset 方式使用，则 encode 规则能够正常工作

技术分析

问题根源

经过代码分析，问题出在 WhiskerBoxCommonMixin 的 getInitialData() 方法中。该方法在处理类别轴时，会无条件地将 ordinalMeta 设置为"基础"维度，并将其作为第0个值维度插入到系列数据中。这一行为直接覆盖了用户通过 encode 配置项指定的规则。

核心逻辑缺陷

当前实现中，无论用户是否通过 encode 指定了x/y轴的映射关系，只要检测到类别轴，就会强制添加 ordinal 维度。这种设计过于武断，没有考虑用户可能通过 encode 配置项明确指定了维度映射关系的情况。

解决方案

修复思路

合理的修复方案应该是在添加 ordinal 维度前，先检查用户是否通过 encode 配置项明确指定了x/y轴的映射关系。只有当用户没有明确指定时，才执行默认的维度添加逻辑。

具体实现

在 getInitialData() 方法中，修改类别轴处理的逻辑：

const encodeRules = this.getEncode();

if (xAxisType === 'category') {
    option.layout = 'horizontal';
    ordinalMeta = xAxisModel.getOrdinalMeta();
    addOrdinal = !encodeRules?.data?.has('x'); // 仅在未指定x映射时添加
}
else if (yAxisType === 'category') {
    option.layout = 'vertical';
    ordinalMeta = yAxisModel.getOrdinalMeta();
    addOrdinal = !encodeRules?.data?.has('y'); // 仅在未指定y映射时添加
}
else {
    option.layout = option.layout || 'horizontal';
}

修复效果

这一修改后：

1. 当用户通过 encode 明确指定了维度映射关系时，系统会尊重用户的配置
2. 当用户没有指定时，系统会保持原有的默认行为
3. 确保了 dataset 和 series.data 两种数据指定方式的行为一致性

最佳实践建议

对于使用 boxplot 图表的开发者，建议：

1. 明确指定 encode 配置项，特别是当使用类别轴时
2. 优先考虑使用 dataset 方式指定数据，这种方式的行为更加稳定
3. 在复杂场景下，可以通过 console.log 输出 seriesModel.getEncode() 的值来验证编码规则是否被正确应用

总结

这个问题的修复体现了配置优先级原则：用户显式指定的配置应该优先于框架的默认行为。通过这次修复，Apache ECharts 的 boxplot 图表在数据编码方面提供了更加灵活和可靠的行为，使开发者能够更精确地控制图表的数据映射关系。