Skip to content
ECharts 概述
ECharts 是 Apache 软件基金会旗下的开源可视化图表库，使用 JavaScript 编写，基于 Apache License 2.0 开源，可以免费商用。
它的核心工作方式是声明式配置：使用一个名为 option 的 JavaScript 对象描述图表的全部内容——图表类型、坐标系、数据、样式、交互组件——然后交给 ECharts 渲染。开发者不需要关心 Canvas API 调用或元素位置计算，只需要描述“画什么”。
官方文档将 ECharts 定位为“基于 JavaScript 的开源可视化图表库”。它既不是 D3 那样底层、自由的可视化语法，也不只是 Chart.js 那种即插即用的简单封装。它在两者之间找到了一个平衡点：提供足够丰富的图表类型和交互能力，同时保持较低的入门成本。
基本概念
ECharts 通过 echarts.init 创建一个实例，然后使用 setOption 方法传入 option 对象完成图表的初次渲染和后续更新。option 是一个纯粹的 JavaScript 数据结构，同时描述静态外观和动态行为。数据或配置发生变化时，再次调用 setOption 传入新的 option，ECharts 内部会自动处理新旧配置的合并、动画过渡，以及坐标系、图例等组件的同步。
核心特性
声明式配置。option 是一个可序列化的描述对象，除少数回调函数外，都可以通过 JSON 表达。这一特性使 ECharts 特别适合集成到 BI 工具、低代码平台等需要动态生成图表配置的环境中。
丰富的图表类型。内置图表类型覆盖了常见的可视化需求，从基础的折线图、柱状图、饼图，到地理地图、热力图、关系图、桑基图、仪表盘、雷达图，均可以直接使用。每个系列在 option 中对应一个 series.type 值，多个系列可以混合使用，比如在同一个直角坐标系中叠加柱状图和折线图。
交互与动画。鼠标悬浮高亮、提示框（tooltip）、图例筛选等交互默认开启，不需要额外编码。数据更新时支持过渡动画——新数据进入、旧数据退出、排序变化都有平滑的视觉反馈。拖拽区域缩放、工具栏保存图片等功能通过添加对应组件即可启用。
多渲染器。支持 Canvas 和 SVG 两种渲染方式。Canvas 适合数据量较大的场景，SVG 适合对交互响应和移动端清晰度要求较高的场景。初始化实例时通过 renderer 参数指定，可选 'canvas'（默认）或 'svg'。
大数据量。Canvas 渲染器下，散点图、线图等类型做了增量渲染优化，可以处理数万甚至十万级别的数据点。
此外，ECharts 还内置了两套主题（亮色和暗色），支持通过 echarts.init(dom, 'dark') 切换；支持通过 toolbox 组件直接保存图表为图片；图表不会自动跟随容器大小变化，但在窗口尺寸改变时调用 resize 方法即可自适应。
从 4.0 开始加入的 dataset 组件允许以二维表结构管理数据，多个系列可以共享同一份数据源，再通过 series.encode 指定列映射。当数据来自 CSV 或数据库时，这比在每个 series.data 中重复声明数据更简洁。
图表类型概览
ECharts 的内置图表类型按使用场景大致可以分为以下几类。
直角坐标系图表，需要 xAxis、yAxis，并通过 grid 控制布局：
- 柱状图（
bar）：分类比较、排名 - 折线图（
line）：趋势、时序变化 - 面积图：
line系列配合areaStyle - 散点图（
scatter）：分布、相关性 - 气泡图（
scatter配合symbolSize映射到数据值） - K 线图（
candlestick）：金融数据 - 箱线图（
boxplot）：统计分布 - 瀑布图（叠加
stack的柱状图变体） - 柱线混合图：多个
series混合bar和line
极坐标系图表，需要 polar、radiusAxis 和 angleAxis：
- 极坐标柱状图、极坐标散点图、极坐标气泡图等
地理坐标系图表，需要 geo 组件或 map 系列：
- 地理散点图、区域着色地图（
map）、路径图（lines，用于航线、迁移等） - 5.3.0 开始支持自定义 SVG 底图
无坐标系图表：
- 饼图（
pie）：占比 - 环形图（
pie配合radius设置内外半径） - 南丁格尔玫瑰图（
pie配合roseType）
层级和关系图表：
- 树图（
tree）、矩形树图（treemap）、旭日图（sunburst） - 关系图（
graph），支持力导向布局，常用于网络拓扑、知识图谱 - 桑基图（
sankey）、漏斗图（funnel）
统计和特殊图表：
- 热力图（
heatmap）、仪表盘（gauge）、雷达图（radar） - 主题河流图（
themeRiver）、日历热力图（calendar+heatmap） - 平行坐标图（
parallel） - 3D 图表（需引入 echarts-gl 扩展）
常用组件（不直接对应 series.type，但与图表配合使用）：
tooltip：悬浮提示框，默认启用legend：图例，点击可筛选系列toolbox：工具栏，可包含保存图片、数据视图、缩放还原等功能dataZoom：区域缩放和滚动条visualMap：视觉映射，将数值映射到颜色、大小、透明度brush：圈选工具timeline：时间轴，用于轮播多组数据
一个典型的趋势分析图表通常由 grid、xAxis、yAxis、line 系列、tooltip 和 dataZoom 等多个部分组合而成。
基本用法
引入 ECharts
通过 CDN 引入：
html
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>使用 npm 安装：
bash
npm install echartsjavascript
import * as echarts from 'echarts';按需引入时，部分系列（如地图）需要通过 echarts.use 显式注册。全量引入不受此影响。
初始化实例并设置 option
完成第一个图表只需要三步：准备一个具有确定宽高的 DOM 容器 → 初始化 ECharts 实例 → 调用 setOption 传入 option。
html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>ECharts 快速体验</title>
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
</head>
<body>
<!-- 1. 准备容器 -->
<div id="chart" style="width: 600px; height: 400px;"></div>
<script>
// 2. 初始化实例
const chartDom = document.getElementById('chart');
const chart = echarts.init(chartDom);
// 3. 用 option 描述图表并渲染
chart.setOption({
title: { text: '月度销售额' },
xAxis: { type: 'category', data: ['1月', '2月', '3月', '4月', '5月', '6月'] },
yAxis: { type: 'value' },
series: [{
type: 'bar',
data: [320, 450, 280, 510, 390, 620]
}]
});
</script>
</body>
</html>打开页面后，浏览器会渲染一张包含标题和坐标轴的柱状图。鼠标移到柱子上会出现提示框，显示对应的数值和类目名。数据的配置直接写在 series.data 中。
这个示例展示了 ECharts 的核心模式：容器是一个普通的 <div> 元素，图表大小默认等于容器的 CSS 尺寸（容器必须显式指定宽高，否则图表无法正常显示）。echarts.init(dom) 返回一个实例，同一个 DOM 节点上多次调用 init 会返回已存在的实例，而不是重复创建。setOption 是声明式的，描述的是图表的目标状态，ECharts 负责从当前状态过渡到目标状态。
容器大小管理
图表不会自动监听容器尺寸的变化。当容器因布局调整而改变大小时，需要手动调用 resize：
javascript
window.addEventListener('resize', () => {
chart.resize();
});实例不再使用时，调用 dispose 释放资源：
javascript
chart.dispose();典型使用场景
ECharts 解决的核心问题是：在 Web 页面中快速生成可交互的数据可视化图表，同时保留足够的定制空间。
不是所有可视化需求都需要从底层构建。当需要一个带 tooltip 的柱状图、一个支持缩放的时间序列图、一张可下钻的地图时，ECharts 的组件和内置交互能力可以直接使用，无需自行处理 Canvas 重绘时机、坐标转换、不同像素密度下的渲染等问题。
常见场景包括：
- 数据监控大屏：多图表组合、定时刷新、暗色主题。
resize方法和百分比布局天然适配大屏的窗口尺寸变化。 - 运营分析报表：柱状图、折线图、饼图组合，配合图例筛选和区域缩放，帮助运营人员探索数据。
- 地理数据展示：通过
geo或map系列展示区域销售分布、物流路径、POI 分布等。5.3.0 引入的自定义地理投影允许对接d3-geo等库实现更灵活的投影。 - 关系网络分析：
graph系列绘制力导向布局的关系图，用于知识图谱、社交网络、设备拓扑等。 - BI 工具和低代码平台：option 结构可序列化，适合作为图表的渲染引擎，由平台动态生成配置。
与 D3.js、Chart.js 的对比
D3.js 是更底层的数据可视化工具。它不提供“图表”的概念，而是提供数据绑定、比例尺、布局算法、SVG/Canvas 操作等基础能力。用 D3 可以构建任意形式的可视化，但每个 tooltip、每个坐标轴、每个图例都需要自己实现。适合需要高度定制化的场景，但很不适合快速产出常规图表。
Chart.js 在另一个方向上极简：几行代码就能生成常见的几种图表类型，但图表种类较少，交互和组件的丰富程度远低于 ECharts。适合对图表要求不高、追求包体积极小的页面。
ECharts 介于二者之间：图表类型多，交互组件开箱即用，同时通过 option 的深度配置保留了较高的可定制性。学习成本比 Chart.js 高，但比 D3 低得多——需要掌握的是 option 的配置逻辑，而不是图形渲染原理。
生态与学习资源
- 官方文档：Apache ECharts 官网（echarts.apache.org）提供完整的中英文配置项手册、示例和版本更新记录。
- 官方示例：官网提供了数百个可在线编辑的示例，覆盖所有图表类型和组件，可以直接在浏览器中修改 option 并实时预览。
- 主题构建：官方在线主题编辑器支持可视化调整颜色、字体、边框等，并导出主题 JSON。
- 扩展包：echarts-gl（3D 图表）、echarts-wordcloud（词云）等。
- 社区：官方推荐在 Stack Overflow、开源中国、SegmentFault 等平台提问；awesome-echarts 仓库收集了教程、工具和社区作品。
注意点
版本变化。如果使用 ECharts 5.3.0 及以上版本，有两处行为与之前不同：
- 折线图默认不再在鼠标悬浮时加粗折线。旧版本中该效果默认开启，如需恢复，应设置
emphasis.lineStyle.width: 'bolder'。 MapChart的注册方式调整：按需引入时需要先通过echarts.use([MapChart])注册地图系列，然后才能使用registerMap。全量引入不受影响。
安全考虑。ECharts 的部分配置项允许传入 HTML 字符串（如 tooltip.formatter）或 JavaScript 函数（如 label.formatter）。当这些配置的值来自不可信任的输入源时，存在 XSS 风险。ECharts 的安全模型假设输入来自可信任来源，不会自动对内容做净化处理。对于来自用户输入的内容，建议使用 echarts.format.encodeHTML 进行转义，或使用 DOM API 的 textContent 设置文本。另外，dataset.transform 中的正则配置如果构造了灾难性回溯模式，可能导致 CPU 指数级消耗，影响可用性。
Vue 中的使用。在 Vue 中使用 ECharts 实例时，应避免将实例放入 reactive、ref 或 data 等响应式容器。实例被 Vue 响应式系统代理后可能引发图表行为异常和性能下降。正确的做法是使用普通变量存储，或者使用 shallowRef、shallowReactive、markRaw 防止深层代理。
参考链接
- [1] https://echarts.apache.org/zh/faq.html
- [2] https://echarts.apache.org/handbook/zh/get-started
- [3] https://echarts.apache.org/handbook/zh/concepts/chart-size
- [4] https://echarts.apache.org/handbook/zh/basics/release-note/5-3-0
- [6] https://echarts.apache.org/handbook/zh/concepts/dataset
- [10] https://echarts.apache.org/handbook/zh/best-practices/security
- [13] https://echarts.apache.org/handbook/zh/how-to/component-types/geo/svg-base-map
- [16] https://github.com/apache/echarts-doc