JS 统计图快速入门：使用 ECharts 渲染第一个柱状图

一、准备阶段：引入脚本与划定容器

ECharts 可以通过 npm 安装在现代化前端工程中，也可以直接在 HTML 页面中通过 <script> 标签引入。对于初学者或快速验证场景，通过公共 CDN 引入是最直接的方式。

在 HTML 的 <head> 或 <body> 底部，引入官方发布的 echarts.min.js 文件后，浏览器全局对象中就会注入名为 echarts 的顶级命名空间：

<!-- 通过 CDN 加载 ECharts 最新 5.x 版本 -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>

接下来需要在页面主体中为图表开辟一个宿主节点。ECharts 底层依赖 HTML5 Canvas（或 SVG）进行矢量图形绘制，绘制引擎在初始化瞬间必须获取容器的物理像素宽高。

<!-- 具有固定尺寸的图表容器 -->
<div id="main" style="width: 600px; height: 400px;"></div>

二、初始化图表实例

有了 DOM 节点与全局 echarts 变量后，即可通过 echarts.init() 方法创建图表实例。这个方法会读取目标 DOM 节点的几何尺寸，在节点内部动态创建用于图形绘制的 <canvas> 画布，并返回一个可供后续调用的实例对象。

// 1. 获取刚刚声明的 DOM 节点
const chartDom = document.getElementById('main');

// 2. 初始化 ECharts 实例
const myChart = echarts.init(chartDom);

需要注意的是，这一行代码必须在 DOM 节点已经成功加载到文档树之后才能执行。如果将脚本直接放在 <head> 区域且没有添加 defer 或事件监听，getElementById 将返回 null，导致报错。

三、核心配置：拆解柱状图的 Option 结构

ECharts 的核心设计理念是“声明式配置驱动”。开发者不需要手动计算柱子的像素坐标、宽度或间距，只需要通过一个名为 option 的 JavaScript 普通对象，声明坐标轴类型、刻度名称、图表种类以及对应的数据数组。

一个最基础、能完整表达业务含义的柱状图，通常包含以下五个核心配置项：

在配置对象编写完成后，调用实例的 setOption(option) 方法，ECharts 就会解析这些配置，并在底层的 Canvas 绘图上下文上一气呵成地渲染出所有坐标轴、网格与柱体。

四、完整示例：一键运行的柱状图页面

将上述各个环节整合，得到如下这份完全独立的 HTML 代码文件。你可以将代码保存为 index.html 并在任何现代浏览器中双击直接打开：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>ECharts 第一个柱状图示例</title>
  <!-- 1. 引入 ECharts 库 -->
  <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
</head>
<body>
  <!-- 2. 准备具备固定宽高的 DOM 容器 -->
  <div id="chart-container" style="width: 700px; height: 420px; margin: 30px auto;"></div>

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

    // 4. 编写图表配置项
    const option = {
      title: {
        text: '上半年数码配件销量统计',
        subtext: '单位：百件',
        left: 'center'
      },
      tooltip: {
        trigger: 'axis',
        axisPointer: {
          type: 'shadow'
        }
      },
      xAxis: {
        type: 'category',
        data: ['1月', '2月', '3月', '4月', '5月', '6月']
      },
      yAxis: {
        type: 'value'
      },
      series: [
        {
          name: '销量',
          type: 'bar',
          data: [120, 200, 150, 80, 170, 230],
          barWidth: '40%',
          itemStyle: {
            color: '#6487A5',
            borderRadius: [4, 4, 0, 0]
          }
        }
      ]
    };

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

    // 6. 监听窗口尺寸变化，保证自适应
    window.addEventListener('resize', () => {
      myChart.resize();
    });
  </script>
</body>
</html>

五、数据绑定与坐标对齐机制

初次接触柱状图时，常有读者疑惑：ECharts 是如何知道 120 应该画在 1月 上方，而不是 2月 上的？

答案在于数组下标的严格隐式对齐。在基础柱状图中，xAxis.data 数组与 series[0].data 数组通过索引保持一一对应：

• xAxis.data[0]（'1月'）对应 series.data[0]（120）
• xAxis.data[1]（'2月'）对应 series.data[1]（200）
• 如果两个数组的长度不一致，多出的一侧将无法正确配对渲染，导致柱体缺失或末尾类目留白。

为了让柱状图更具视觉舒适度，通常会通过以下两个属性进行微调：

1. 柱子宽度 barWidth：默认情况下柱子会根据分类间距自动拉宽，显得过于拥挤。设置为百分比字符串（如 '35%'）或固定数值像素（如 24），可以让柱列疏密得当。
2. 顶部圆角 borderRadius：设置 borderRadius: [4, 4, 0, 0]（分别对应左上、右上、右下、左下四个角），可以去除尖锐的直角，呈现现代UI平滑柔和的过渡质感。

六、新手常见问题与排错指南

在实际编写代码过程中，初学者通常会遭遇三类典型问题。以下是其具体表现、诱发原因与对应的解决方案：

1. 控制台报错：Initialize failed: invalid dom.

原因解释：当执行 document.getElementById('main') 时，浏览器尚未解析到 HTML 中的对应 <div> 标签，返回了 null。ECharts 无法在空对象上建立画布上下文，因而抛出异常。

解决方法：确保 <script> 代码块放置在容器 <div> 的下方，或者将初始化代码包裹在 document.addEventListener('DOMContentLoaded', ...) 事件回调中执行。

2. 页面完全空白，但控制台无任何错误

原因解释：这是最普遍的现象。容器虽然在 DOM 中存在，但未显式设置 CSS 高度，或者父级元素具有 display: none。ECharts 读取到的容器尺寸为 0 × 0，Canvas 生成的高度同样为 0。

解决方法：在容器内联样式或 CSS 类中，务必添加 height: 400px;（确保为非零绝对值或具有确定高度的百分比环境）。

3. 窗口缩放后图表不随之自适应

原因解释：Canvas 是基于位图渲染的，一旦渲染完成，其像素尺寸就被固定。当浏览器窗口被拖拽缩小或放大时，ECharts 不会自动检测视口变化。

解决方法：在初始化代码后，监听 window 的 resize 事件，并显式调用 myChart.resize() 方法，让 ECharts 重新计算容器的当前像素尺寸并执行重绘。

七、总结

使用 ECharts 渲染柱状图的核心在于建立“容器—实例—配置”的认知模型。一旦理解了 DOM 容器提供物理画布、ECharts 实例管理底层渲染引擎、Option 纯数据对象声明视觉映射的内在关系，后续无论是扩展为多系列堆叠柱状图、切换为横向条形图，还是引入折线图混合渲染，其底层逻辑都完全一致。