TOAST UI Chart v4.0 迁移指南：从技术专家视角解析重大变更

冯爽妲Honey

于 2025-06-08 09:03:01 发布

阅读量365

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00256/article/details/148505683

TOAST UI Chart v4.0 迁移指南：从技术专家视角解析重大变更

tui.chart 项目地址: https://gitcode.com/gh_mirrors/tui/tui.chart

引言

TOAST UI Chart 4.0 版本是一次重大升级，基于 canvas 技术重构，移除了外部依赖并支持 tree shaking，带来了更轻量的开发体验。本文将作为技术专家视角的迁移指南，帮助开发者全面理解这次升级的核心变化。

核心变更解析

1. 安装方式变更

包名与命名空间调整

包名变更：从 tui-chart 变更为 @toast-ui/chart
命名空间调整：全局命名空间从 tui 改为 toastui

# 旧版安装
npm install tui-chart

# 新版安装
npm install @toast-ui/chart

按需引入优化

4.0 版本支持更精细的模块化引入：

// 完整引入
import Chart from '@toast-ui/chart';

// 按图表类型引入
import { BarChart } from '@toast-ui/chart';

资源文件调整

CSS 文件路径变更：

import '@toast-ui/chart/dist/toastui-chart.css';

移除了包含所有依赖的 -all 版本和包含 polyfill 的版本

2. 图表创建方式重构

新旧 API 对比

// 旧版 (v3.x)
const chart = Chart.barChart(el, data, options);

// 新版 (v4.0)
// 方式1：静态方法
const chart = Chart.barChart({el, data, options});

// 方式2：构造函数
import { BarChart } from '@toast-ui/chart';
const chart = new BarChart({el, data, options});

组合图表命名规范化

| 旧版名称 | 新版名称 | 说明 | |---------|---------|------| | comboChart | nestedPieChart | 嵌套饼图 | | comboChart | columnLineChart | 柱线组合图 | | comboChart | lineAreaChart | 线面积组合图 |

3. 主题系统升级

4.0 版本对主题系统进行了全面重构：

// 旧版主题注册
Chart.registerTheme('myTheme', themeConfig);

// 新版主题配置
const options = {
  theme: {
    chart: { /* 全局样式 */ },
    series: { /* 系列样式 */ },
    tooltip: { /* 提示框样式 */ }
  }
};

// 动态更新主题
chart.setOptions({
  theme: {
    series: { colors: ['#FF0000', '#00FF00'] }
  }
});

4. 提示框(Tooltip)增强

数据格式化更灵活

// 旧版简单格式化
chart: { format: '1,000' },
tooltip: { suffix: '℃' }

// 新版函数式格式化
tooltip: {
  formatter: (value) => {
    return `${value.toFixed(2)} ℃`;
  }
}

模板系统升级

新版提供了更丰富的模板参数：

tooltip: {
  template: (model, defaultTemplate, theme) => {
    return `
      <div style="background: ${theme.background}">
        <p>${model.category}</p>
        ${defaultTemplate.body}
      </div>
    `;
  }
}

5. 坐标轴优化

刻度与标签间隔

4.0 版本简化了间隔配置：

// 旧版
xAxis: {
  tickInterval: 'auto',
  labelInterval: 2
}

// 新版
xAxis: {
  tick: {
    interval: (axis) => Math.ceil(axis.dataCount / 5)
  },
  label: {
    interval: 2
  }
}

6. 数据标签配置变更

数据标签样式从直接配置迁移到主题系统：

// 旧版
series: {
  dataLabels: {
    visible: true,
    anchor: 'center'
  }
}

// 新版
theme: {
  series: {
    dataLabels: {
      visible: true,
      anchor: 'center'
    }
  }
}

7. 嵌套饼图(NestedPie)重构

原 Pie&Donut 组合图重命名为 NestedPie，数据格式也进行了调整：

// 新版数据结构
const data = {
  categories: ['A', 'B'],
  series: [
    {
      name: 'Alpha',
      data: [
        { name: 'A1', data: 10 },
        { name: 'A2', data: 20 }
      ]
    },
    {
      name: 'Beta',
      data: [
        { name: 'B1', data: 30 },
        { name: 'B2', data: 40 }
      ]
    }
  ]
};

8. 响应式布局增强

4.0 版本引入了更完善的响应式方案：

const options = {
  chart: {
    width: 'auto',
    height: 'auto'
  },
  responsive: {
    animation: { duration: 300 },
    rules: [
      {
        condition: ({ width }) => width < 500,
        options: {
          legend: { visible: false }
        }
      }
    ]
  }
};