Chart.js v3/v4 迁移指南：API 变更与配置项替换

一、模块引入与 Tree-shaking 注册改造

在 Chart.js v2 时代，引入库的方式通常是直接全量导入整个 Chart 对象。由于 v2 内部将所有类型的图表控制器（折线、柱状、雷达、极坐标等）、刻度尺算法以及内置插件强行绑死在一个打包产物内，即便项目仅需要绘制一条基础折线，生产构建也会完整携带 200KB 以上的代码。从 v3 开始，Chart.js 正式拥抱现代化构建工具的摇树优化能力，但也带来了全新的初始化契约。

1. 方案选择：快速全量包与精细按需注册

对于迁移初期希望以最低成本恢复图表展示的项目，Chart.js 官方提供了内置自动注册机制的独立入口 chart.js/auto。只要将原本的导入路径做简单的别名替换，系统就会在后台自动完成全部内置控制器与插件的注册：

// 方案 A：快速兼容模式（引入包含全量注册的 auto 包）
import Chart from 'chart.js/auto';

// 直接按照后续新配置语法实例化即可
const chart = new Chart(ctx, config);

如果项目对首屏加载性能与生产包体积有严苛要求，应当采用推荐的按需注册方案。在该方案中，核心 Chart 类本身只是一个空调度器，开发者必须显式调用 Chart.register(...) 将使用到的控制器（Controllers）、图形元素（Elements）、刻度尺度（Scales）与插件（Plugins）注册进全局运行注册表：

// 方案 B：精细按需 Tree-shaking 注册模式（推荐生产环境使用）
import {
  Chart,
  LineController,
  LineElement,
  PointElement,
  LinearScale,
  CategoryScale,
  Title,
  Tooltip,
  Legend
} from 'chart.js';

// 显式完成依赖项注入，未引用的组件将被 Rollup / Webpack 彻底剔除
Chart.register(
  LineController,
  LineElement,
  PointElement,
  LinearScale,
  CategoryScale,
  Title,
  Tooltip,
  Legend
);

二、核心配置项层级重构与命名空间收敛

配置项结构是 v2 到 v3/v4 迁移过程中代码变动量最大的区域。在旧版本中，配置项呈现两极分化：一部分关键功能（如标题、图例、浮层提示）散落在 options 顶层，容易与其他配置产生命名冲突；另一部分（如坐标轴体系）则采用了复杂的数组嵌套形式，导致多轴定义和跨轴引用十分繁琐。

1. 坐标轴体系（Scales）：由数组变更为对象字典

在 v2 中，坐标轴必须定义在 options.scales.xAxes 和 options.scales.yAxes 数组中。如果需要定义双 Y 轴，必须在数组项中手写 id: 'y-axis-1'。在 v3 及更高版本中，数组被彻底废弃，统一使用以轴 ID 作为键名的对象字典：

// v2: 数组形式
options: {
  scales: {
    xAxes: [{
      gridLines: { display: false },
      scaleLabel: {
        display: true,
        labelString: '月份'
      }
    }],
    yAxes: [{
      ticks: { beginAtZero: true }
    }]
  }
}

// v3/v4: 对象字典与新属性名
options: {
  scales: {
    x: {
      grid: { display: false }, // gridLines -> grid
      title: {                   // scaleLabel -> title
        display: true,
        text: '月份'              // labelString -> text
      }
    },
    y: {
      beginAtZero: true          // 轴配置根属性或 ticks 均可
    }
  }
}

2. 插件体系（Plugins）：统一收拢至 options.plugins

v2 顶层的 legend、title 以及复数形式的 tooltips，从 v3 起一律收归于 options.plugins 命名空间之下，同时 tooltips 更名为单数形式的 tooltip。如果在 v3/v4 中仍写在 options 根级别，系统将直接忽略这些配置，导致图例不渲染或浮层无动静：

// v3 / v4 规范的插件配置结构
const options = {
  responsive: true,
  plugins: {
    title: {
      display: true,
      text: '季度经营趋势汇总'
    },
    legend: {
      display: true,
      position: 'bottom'
    },
    tooltip: { // 注意：单数 tooltip，而非 tooltips
      enabled: true,
      mode: 'index',
      intersect: false
    }
  }
};

三、回调函数与事件交互 API 升级

当图表需要定制悬浮提示文案或响应用户的画布点击时，旧版的回调函数签名和事件查询方法同样发生了结构性变更。理解新的 context 契约是避免生产运行时报空指针的关键。

1. Tooltip Callback 签名统一

在 v2 中，Tooltip 回调函数通常接收两个参数：(tooltipItem, data)，开发者需要通过 data.datasets[tooltipItem.datasetIndex].data[tooltipItem.index] 去绕弯寻找原始数据。而在 v3/v4 中，回调统一接收单参数 context，上下文对象中已经封装好了解析后的数值、原始数据项及对应样式：

// v3 / v4 规范 Tooltip 回调函数
options: {
  plugins: {
    tooltip: {
      callbacks: {
        label: function(context) {
          // context.parsed: 解析后的数值对象 (例如 { x: 0, y: 120 })
          // context.raw: 数据集数组中的原始输入项
          // context.dataset.label: 当前序列名称
          const val = context.parsed.y !== null ? context.parsed.y : context.raw;
          return `${context.dataset.label}: ¥${val.toLocaleString()}`;
        }
      }
    }
  }
}

2. 元素交互查找 API 替换

在 v2 中，处理点击事件通常调用 chartInstance.getElementAtEvent(e) 或 chartInstance.getElementsAtEvent(e)。从 v3 开始，这两个方法被标记废弃，并在 v4 中被完全移除。现代规范要求统一使用 getElementsAtEventForMode 方法，并明确传入交互查找模式：

// 画布点击事件响应规范
canvas.onclick = function(evt) {
  // v3 / v4 标准查找方法：指定查找模式、交叉规则与是否仅精确匹配
  const points = chart.getElementsAtEventForMode(
    evt,
    'nearest',
    { intersect: true },
    false
  );

  if (points.length > 0) {
    const firstPoint = points[0];
    const datasetIndex = firstPoint.datasetIndex;
    const index = firstPoint.index;
    const value = chart.data.datasets[datasetIndex].data[index];
    console.log(`选中序列 [${datasetIndex}] 第 [${index}] 项数据:`, value);
  }
};

四、平滑迁移实施路径四步法

面对业务系统中的多张图表，建议按照系统化的四个步骤推进升级，逐步定位并隔离问题，避免一揽子修改导致排错无从下手。

1. 依赖审查与环境准备：更新 package.json。若项目中使用了时间刻度尺（type: 'time'），必须额外安装独立的时间适配器（如 chartjs-adapter-date-fns），因为 Chart.js v3 起移除了内置的 Moment.js。
2. 确立组件注册策略：在业务代码入口处，根据性能诉求决定是使用快速过渡的 chart.js/auto，还是配置 Chart.register(...) 按需注册。
3. 重构配置树字典：重点检索源码中的 xAxes、yAxes、gridLines、scaleLabel，将其映射替换为新版对象字典，并将 legend、title、tooltips 移动至 plugins 命名空间。
4. 验证回调与事件交互：检查所有 Tooltip 的 callbacks 实现以及通过 getElementAtEvent 绑定的点击钻取逻辑，替换为单参数 context 与 getElementsAtEventForMode。

五、Chart.js v3 到 v4 的增量演进要点

如果你的项目当前已经处于 v3 版本，或者正计划直接一步到位迈向 v4，需要特别注意 v4 引入的增量规范调整。与 v2 到 v3 的天翻地覆相比，v3 到 v4 更多体现为现代 JavaScript 生态的规范收拢：

1. 纯 ESM 模块发布机制

Chart.js v4 遵循现代前端社区规范，包产物采用了纯 ESM 模块分发。如果你的工程仍然运行在传统的 CommonJS 环境中（例如未经打包工具处理的 Node.js 脚本或部分老旧测试框架），直接使用 const { Chart } = require('chart.js') 将报错。解决方案为升级构建工具支持 ESM，或改用动态 import('chart.js')。

2. 全局默认配置扁平化与文字排版简化

在旧版中，修改全局文字配置往往需要修改 Chart.defaults.global.defaultFontSize。v3 将其清理为 Chart.defaults.font.*。在 v4 中，全局字体结构保持一致且进一步强化了继承机制，可以通过一个统一对象进行配置：

// v4 全局默认字体配置
Chart.defaults.font = {
  family: "'PingFang SC', 'Microsoft YaHei', sans-serif",
  size: 13,
  weight: 'normal',
  lineHeight: 1.5
};

3. 内置色彩插件（Colors Plugin）

在以往版本中，未指定 backgroundColor 的序列默认会呈现单调的灰色。Chart.js v4 官方内置了无障碍色彩插件。在按需引入模式下，只需注册 Colors 插件，图表就会自动应用规范的调色板：

import { Chart, Colors } from 'chart.js';

// 注册后所有未显式定义色值的 dataset 将自动轮转区分色彩
Chart.register(Colors);

六、常见迁移报错速查表

下表汇总了迁移过程中最常遇见的报错信息、诱发原因以及直接修复方案：