ECharts合并X轴配置时出现boundaryGap类型不兼容TS错误

问题背景 #

合并initialXAxis和xAxis选项时触发TypeScript类型错误，错误提示boundaryGap属性类型不兼容，但代码中并未显式设置该属性。根据ECharts官方文档，类目轴的boundaryGap仅支持布尔值，默认值为true，无需用户手动指定，怀疑这是ECharts库的TS类型Bug。

错误信息 #

Type '{ type: "category"; data: any[]; axisLabel: { formatter: (value: string) => string; }; scale?: boolean | undefined; boundaryGap?: [string | number, string | number] | undefined; splitNumber?: number | undefined; ... 40 more ...; categorySortInfo?: OrdinalSortInfo | undefined; } | { ...; } | { ...; } | { ...; } | { ....' is not assignable to type 'XAXisOption | XAXisOption[] | undefined'.
  Type '{ type: "category"; data: any[]; axisLabel: { formatter: (value: string) => string; }; scale?: boolean | undefined; boundaryGap?: [string | number, string | number] | undefined; splitNumber?: number | undefined; ... 40 more ...; categorySortInfo?: OrdinalSortInfo | undefined; }' is not assignable to type 'XAXisOption | XAXisOption[] | undefined'.
    Type '{ type: "category"; data: any[]; axisLabel: { formatter: (value: string) => string; }; scale?: boolean | undefined; boundaryGap?: [string | number, string | number] | undefined; splitNumber?: number | undefined; ... 40 more ...; categorySortInfo?: OrdinalSortInfo | undefined; }' is not assignable to type '(AxisBaseOptionCommon & { gridIndex?: number | undefined; gridId?: string | undefined; position?: CartesianAxisPosition | undefined; offset?: number | undefined; categorySortInfo?: OrdinalSortInfo | undefined; } & { ...; }) | (CategoryAxisBaseOption & ... 1 more ... & { ...; })'.
      Type '{ type: "category"; data: any[]; axisLabel: { formatter: (value: string) => string; }; scale?: boolean | undefined; boundaryGap?: [string | number, string | number] | undefined; splitNumber?: number | undefined; ... 40 more ...; categorySortInfo?: OrdinalSortInfo | undefined; }' is not assignable to type 'CategoryAxisBaseOption & { gridIndex?: number | undefined; gridId?: string | undefined; position?: CartesianAxisPosition | undefined; offset?: number | undefined; categorySortInfo?: OrdinalSortInfo | undefined; } & { ...; }'.
        Type '{ type: "category"; data: any[]; axisLabel: { formatter: (value: string) => string; }; scale?: boolean | undefined; boundaryGap?: [string | number, string | number] | undefined; splitNumber?: number | undefined; ... 40 more ...; categorySortInfo?: OrdinalSortInfo | undefined; }' is not assignable to type 'CategoryAxisBaseOption'.
          Types of property 'boundaryGap' are incompatible.
            Type '[string | number, string | number] | undefined' is not assignable to type 'boolean | undefined'.
              Type '[string | number, string | number]' is not assignable to type 'boolean | undefined'.

相关代码 #

import { EChartsOption } from 'echarts';
import dayjs from 'dayjs';

const getOption = (data: any[]): EChartsOption => {
    const initialXAxis: EChartsOption['xAxis'] = {};
    const xAxis: EChartsOption['xAxis'] = {
        ...initialXAxis,
        type: 'category',
        data: data.map((item) => item.issueTime),
        axisLabel: {
            formatter: (value: string) => dayjs(+value).format('HH:mm'),
        },
    };

    const series: EChartsOption['series'] = [];

    return {
        xAxis,
        series,
        yAxis: {},
    };
};

依赖版本 #

"echarts": "^5.4.3"

问题分析与解答 #

结论：这是ECharts TypeScript类型定义的设计缺陷 #

原因：

• EChartsOption['xAxis']是一个联合类型，包含了类目轴、数值轴等所有轴类型的属性集合。当初始化initialXAxis为{}时，TypeScript会推断它的boundaryGap属性可能是数值轴支持的[string | number, string | number]类型。
• 当将其合并到明确指定type: 'category'的类目轴配置时，TypeScript无法自动收缩类型，会认为合并后的对象同时存在两种类型的boundaryGap，从而触发类型冲突。

临时修复方案 #

方案1：显式指定initialXAxis为类目轴类型

直接约束初始对象的类型为类目轴，避免类型歧义：

import { EChartsOption, CategoryAxisOption } from 'echarts';
import dayjs from 'dayjs';

const getOption = (data: any[]): EChartsOption => {
    const initialXAxis: CategoryAxisOption = {};
    const xAxis: CategoryAxisOption = {
        ...initialXAxis,
        type: 'category',
        data: data.map((item) => item.issueTime),
        axisLabel: {
            formatter: (value: string) => dayjs(+value).format('HH:mm'),
        },
    };

    const series: EChartsOption['series'] = [];

    return {
        xAxis,
        series,
        yAxis: {},
    };
};

方案2：合并后显式断言为类目轴类型

通过类型断言告诉TypeScript合并后的对象是类目轴配置：

const xAxis = {
    ...initialXAxis,
    type: 'category',
    data: data.map((item) => item.issueTime),
    axisLabel: {
        formatter: (value: string) => dayjs(+value).format('HH:mm'),
    },
} as CategoryAxisOption;

方案3：省略空对象合并步骤

如果initialXAxis没有实际配置项，直接初始化xAxis即可：

const xAxis: EChartsOption['xAxis'] = {
    type: 'category',
    data: data.map((item) => item.issueTime),
    axisLabel: {
        formatter: (value: string) => dayjs(+value).format('HH:mm'),
    },
};

内容的提问来源于stack exchange，提问作者Lin Du