ECharts快速上手：百度开源图表库JavaScript基础配置实例

图 0：ECharts 运行时挂载机制与声明式 Option 配置概览

一、运行环境准备与开发工序

ECharts 基于底层渲染引擎 ZRender 工作，它并不直接生成 DOM 元素，而是通过 HTML5 Canvas 或 SVG 在给定的容器内绘制矢量图形。因此，图表实例必须依附于一个在页面流中占据实际几何尺寸的元素。

标准接入工序包含从节点声明到窗口响应的完整闭环：

1. 声明容器节点：在 HTML 中放置一个 <div>，并通过内联样式或 CSS 类显式指定 width 和 height。如果宽高为 0，图表在初始化计算坐标时将无法获得有效视口，导致界面空白。
2. 引入库资源：开发排查阶段可直接使用公共 CDN（如 jsDelivr 或 cdnjs）的全局脚本；工程化项目中则通过 npm install echarts 安装并在脚本中按需引入。
3. 初始化图表对象：调用 echarts.init(domElement)，该方法返回一个独立的图表实例，用于管理该区域内的交互、动画与重绘。
4. 应用 Option 选项：定义包含坐标轴与数据序列的 JavaScript 对象，传入 chart.setOption(option) 完成渲染。
5. 绑定尺寸监听：在窗口缩放时调用 chart.resize()，保证图表自适应不同分辨率屏幕。

图 1：ECharts 基础图表构建的标准开发工序

二、完整的最小可运行代码实例

下面是一个单文件即可直接在浏览器打开的完整 HTML 示例。代码创建了一个展示一周访问量的柱状图，包含了标题、浮层提示框与坐标轴的完整声明：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>ECharts 最小实例</title>
  <!-- 1. 引入 ECharts 官方编译文件 -->
  <script src="https://cdn.jsdelivr.net/npm/echarts@5.5.0/dist/echarts.min.js"></script>
  <style>
    /* 必须设置显式宽高，否则画布无法渲染 */
    #main-chart {
      width: 100%;
      max-width: 720px;
      height: 400px;
      margin: 20px auto;
      border: 1px solid #E2ECF3;
      border-radius: 6px;
    }
  </style>
</head>
<body>
  <!-- 2. 图表挂载的实体 DOM 容器 -->
  <div id="main-chart"></div>

  <script>
    // 3. 获取 DOM 节点并初始化实例
    const chartDom = document.getElementById('main-chart');
    const myChart = echarts.init(chartDom);

    // 4. 定义声明式图表配置项
    const option = {
      title: {
        text: '周度用户访问统计',
        subtext: '基础配置演示数据',
        left: 'center'
      },
      tooltip: {
        trigger: 'axis',
        axisPointer: {
          type: 'shadow'
        }
      },
      legend: {
        data: ['访问量'],
        top: 'bottom'
      },
      grid: {
        left: '4%',
        right: '4%',
        bottom: '12%',
        containLabel: true
      },
      xAxis: {
        type: 'category',
        data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
      },
      yAxis: {
        type: 'value',
        name: '单位（人次）'
      },
      series: [
        {
          name: '访问量',
          type: 'bar',
          data: [120, 200, 150, 80, 70, 110, 130],
          itemStyle: {
            color: '#345E82',
            borderRadius: [4, 4, 0, 0]
          }
        }
      ]
    };

    // 5. 将配置应用到图表
    myChart.setOption(option);

    // 6. 响应窗口变化自适应重绘
    window.addEventListener('resize', function () {
      myChart.resize();
    });
  </script>
</body>
</html>

三、核心 Option 配置项分层解析

ECharts 的设计核心是“数据驱动、声明式配置”。传给 setOption 的对象并非过程式绘制指令，而是由若干功能组件构成的树形描述结构。理解各个字段的角色，可以在制作各种复杂图表时保持清晰思路。

图 2：ECharts Option 配置项模块化架构拓扑

1. 交互与说明组件（UI 表现层）

• title（标题）：定义图表的主标题 text 与副标题 subtext。通过 left: 'center' 或数值定位，也可以使用 textStyle 精细控制字体和颜色。
• tooltip（悬浮提示）：鼠标悬停在图表元素上时弹出的浮动卡片。trigger: 'axis' 适用于直角坐标系按轴聚合多组数据，trigger: 'item' 则多用于饼图或散点图单点查看。
• legend（图例组件）：展现不同系列的标记（颜色与名称），用户点击图例可快速筛选或显隐对应的系列。legend.data 中的字符串必须与 series 各项中的 name 严格保持一致。

2. 坐标系统组件（空间定位层）

• grid（直角坐标系网格）：直角坐标系在容器内的绘图区域。默认情况下，坐标轴外部的文字可能溢出容器，将 containLabel 设置为 true 可确保坐标轴标签文本完全包裹在 DOM 视口内。
• xAxis 与 yAxis（坐标轴）： 通常一条设为类目轴（type: 'category'），负责离散字段（如月份、地区、星期）；另一条设为数值轴（type: 'value'），系统会根据传入的数据序列自动推导极值与刻度步长。若交换两者，即可将垂直柱状图直接转为水平条形图。

3. 系列数据层（Series）

series 是一个数组，也是图表真正承载业务数据的核心。每个元素代表一组图形对象，核心属性如下：

四、直角坐标系与多系列数据映射机制

在实际生产业务中，单一柱状图往往无法满足对比需求。通过在 series 数组中添加多个对象，可以在同一个网格坐标系内混合呈现多种图表类型（例如“柱状图 + 折线图”组合）。

图 3：直角坐标系（Grid）与 Series 数据序列的空间映射模型

映射的核心规则是“索引对齐”：当 xAxis.data 声明了 4 个类目节点时，所有依附于该坐标系的 series 数组中的 data 都必须包含相同数量的数据点。ECharts 底层通过索引将相同下标的横纵数值计算出物理像素位置，完成多图元叠加渲染。

以下代码演示了“订单总额（柱状）+ 履约完成率（折线）”的混合配置代码片段：

const multiSeriesOption = {
  title: { text: '销售与履约情况' },
  tooltip: { trigger: 'axis' },
  legend: { data: ['销售额', '完成率'] },
  xAxis: {
    type: 'category',
    data: ['第一季度', '第二季度', '第三季度', '第四季度']
  },
  yAxis: [
    { type: 'value', name: '金额 (万元)' },
    { type: 'value', name: '百分比', max: 100, axisLabel: { formatter: '{value}%' } }
  ],
  series: [
    {
      name: '销售额',
      type: 'bar',
      data: [320, 450, 580, 510],
      itemStyle: { color: '#345E82' }
    },
    {
      name: '完成率',
      type: 'line',
      yAxisIndex: 1, // 绑定至右侧第二根 Y 轴
      smooth: true,
      data: [85, 92, 98, 89],
      itemStyle: { color: '#AD8060' }
    }
  ]
};

五、常见故障排查与运行规范

初学者在使用 ECharts JavaScript API 时，常因前端框架生命周期、DOM 尺寸或实例更新机制等细节遇到渲染异常。以下是经过工程验证的标准排查方案：

图 4：ECharts 常见配置故障与异常排查决策拓扑

1. 图表显示空白或控制台抛出宽度为 0 告警

原因：ECharts 依赖 DOM 的 clientWidth 和 clientHeight 确定画布分辨率。如果容器被设置为 display: none、位于尚未展开的 Tab 页签中，或者未在 CSS 中写入固定高度，容器计算尺寸为 0，画布无法分配像素。

解决办法：为容器指定明确的高度（例如 height: 400px 或 height: 50vh）。若在 Tab 切换中显示，应在切换完成、容器可见后显式调用一次 myChart.resize()。

2. 异步数据请求后视图不刷新

原因：修改了外部 JavaScript 变量后，并未将新配置通知给图表实例。ECharts 不采用双向数据绑定，所有变动必须经由接口触发。

解决办法：在 fetch 或 axios 的成功回调内重新调用 myChart.setOption(...)。值得注意的是，ECharts 默认采用合并策略（merge），即只更新传入的字段；如果后端返回的系列发生减少或需要全量重置，需传入第二个参数 true：

// 异步请求成功后：
fetch('/api/sales')
  .then(res => res.json())
  .then(data => {
    myChart.setOption({
      xAxis: { data: data.categories },
      series: [{ data: data.values }]
    });
  });

// 若需要清空所有旧系列完全覆盖：
myChart.setOption(freshOption, true);

3. 单页应用（SPA）中的实例销毁与内存泄漏

原因：在 Vue、React 或 Angular 单页路由切换时，组件对应的 DOM 节点被销毁，但如果未清理 echarts.init() 创建的实例与 window.resize 监听器，ZRender 仍保留在全局事件池中，引发内存泄漏与重复绑定。

解决办法：在组件卸载钩子（如 Vue 的 onUnmounted 或 React 的 useEffect 返回函数）中执行销毁逻辑：

// 移除全局监听器
window.removeEventListener('resize', resizeHandler);
// 释放图表实例内部资源
if (myChart) {
  myChart.dispose();
  myChart = null;
}