Skip to content
概述
ECharts 实例对外暴露的核心入口是 setOption 方法。无论最简单的柱状图，还是带双轴、缩放与动态更新的仪表板，最终都通过 myChart.setOption(someObject) 完成绘制。option 是一个普通的 JavaScript 对象，其顶层字段各自对应图表中的一个独立部件。理解 option 的结构，也就理解了图表的骨架。
基本概念：option 的 key-value 体系
下面是一个最基础的柱状图 option：
javascript
var option = {
title: { text: 'ECharts 入门示例' },
tooltip: {},
legend: { data: ['销量'] },
xAxis: { data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子'] },
yAxis: {},
series: [{ name: '销量', type: 'bar', data: [5, 20, 36, 10, 10, 20] }]
};标题、提示框、图例、坐标轴和系列被并列在一个对象中。ECharts 内部会逐个解析这些字段，构造出对应的组件树，再由渲染器（Canvas 或 SVG）绘制。每一个顶层字段对应一个组件的配置，组件之间一般通过约定（如 series 里的 xAxisIndex / yAxisIndex）或数据间接关联。
这种 key-value 体系有两个特点：
- 组件解耦——增加标题只需声明
title，移除图例只需去掉legend，不会影响其他配置。 - 默认值宽松——多数组件都有可用的默认行为。例如上例中
yAxis被设为一个空对象，ECharts 会自动生成数值轴并计算合适的刻度范围。
更换图表类型时，只需改动 series[].type 并调整对应的坐标轴类型，很少需要重写整个 option。
series：数据的形状与血肉
series 是一个数组，每个元素描述一组数据以及数据到视觉元素的映射方式。同样的数据，指定不同的 type 会得到完全不同的图表：
javascript
// 柱状图
series: [{ type: 'bar', data: [5, 20, 36, 10, 10, 20] }]
// 折线图
series: [{ type: 'line', data: [5, 20, 36, 10, 10, 20] }]除了 type 与 data，series 中还可以控制坐标轴绑定、视觉通道编码（encode）、样式、标记点等。入门阶段最需要记住的一点是：series 是数据的入口，图表的内容由此决定。
数据并不一定直接写在 series.data 中。ECharts 3 开始提供了 dataset 组件，用二维表结构统一管理数据，再通过 encode 将维度映射到坐标轴、提示框等位置。当 series.data 与 dataset 同时存在时，优先使用 series.data。对于 treemap、graph 这类非表格型图表，只能使用 series.data，不能使用 dataset。
坐标系：xAxis、yAxis 与 grid
轴类型与刻度配置
在直角坐标系图表中，xAxis 和 yAxis 通过 type 声明轴类型。常见的三种类型：
'value'：数值轴，自动计算刻度和范围。'category'：类目轴，用于离散标签（如月份、名称），需要提供data数组。'time'：时间轴，自动解析时间格式并计算合适的时间间隔。
一个双轴配置示例：
javascript
xAxis: {
type: 'time',
name: '销售时间',
axisLabel: { formatter: '{yyyy}-{MM}-{dd}' }
},
yAxis: {
type: 'value',
name: '销售数量',
axisLine: { symbol: 'arrow', lineStyle: { type: 'dashed' } }
}axisLine 配置了轴线两端的箭头与虚线样式；axisLabel.formatter 使用模板字符串定制时间显示。轴上的刻度线、标签、标题均可独立配置。
grid 布局
grid 控制整个直角坐标系绘图区的位置，通过 left、right、top、bottom 定义边距（支持百分比或像素值）。默认布局通常已经足够，但在多轴或嵌套图表场景下需要手动分配。
坐标系与系列的绑定
单个 grid 上最多放置两个 x 轴和两个 y 轴（分别位于上下/左右）。如果需要更多轴，必须使用 offset 错开位置，或增加新的 grid。
不同的 grid 可以各自形成独立的坐标系。系列通过 xAxisIndex 和 yAxisIndex 绑定到指定轴上：
javascript
grid: [{ left: '7%', right: '7%' }, { left: '7%', right: '7%', top: '60%' }],
xAxis: [
{ gridIndex: 0, type: 'category' },
{ gridIndex: 1, type: 'category' }
],
yAxis: [
{ gridIndex: 0 },
{ gridIndex: 1 }
],
series: [
{ xAxisIndex: 0, yAxisIndex: 0, type: 'line', data: [...] },
{ xAxisIndex: 1, yAxisIndex: 1, type: 'bar', data: [...] }
]这个配置中定义了两个 grid（默认上下排列），每个 grid 拥有自己的轴，两条系列分别绑定到不同的 grid 上。不指定 xAxisIndex 时默认值为 0，即与第一个 x 轴绑定。
辅助组件：tooltip、legend、dataZoom、visualMap
tooltip 与 legend
tooltip 控制数据项的悬浮交互。trigger 支持 'item'（数据项触发）和 'axis'（坐标轴触发）。'axis' 会同时展示同一轴上所有系列在当前数据点的值，在折线图与柱状图中最为常用：
javascript
tooltip: {
trigger: 'axis',
axisPointer: { type: 'cross' }
}legend 展示各系列的名称与颜色，点击图例可以切换对应系列的显示/隐藏。图例的 data 应与各系列的 name 保持一致，否则筛选联动无法正确生效。
dataZoom
dataZoom 提供数据区域缩放能力，适合长时间范围或大量类目的场景。启用一个基础滑块缩放只需：
javascript
dataZoom: [{ type: 'slider', start: 10, end: 90 }]type: 'inside' 则支持在图表内部通过鼠标滚轮或触控缩放。多个 dataZoom 组件可以联动控制不同的坐标轴。
visualMap
visualMap 将数据值映射到颜色、大小等视觉通道。例如，将连续数值映射到一条色带：
javascript
visualMap: {
min: 0,
max: 100,
calculable: true,
inRange: { color: ['#50a3ba', '#eac736', '#d94e5d'] }
}系列会自动绑定该映射（也可通过 visualMap.seriesIndex 明确指定），数据点将根据自身数值进行着色。这种方式可以在同一份数据上快速构造出热力图、气泡图等效果。
组件的独立性与联动
各个组件在逻辑上彼此独立。tooltip 不关心 legend 的具体配置，grid 也不干涉 series 的样式。组件之间的联动通过特定的属性建立，例如：
series.xAxisIndex/yAxisIndex—— 绑定坐标系dataZoom.xAxisIndex—— 控制指定轴visualMap.seriesIndex—— 作用于指定系列legend.data与series.name匹配 —— 筛选联动
当图表出现“轴错位”或“缩放失效”等问题，通常是因为索引未对齐或名称不匹配。
从渲染结果反推 option
面对一个较复杂的图表，可以按以下顺序拆解 option：
- 是否有标题？→
title - 左上角图例 →
legend - 悬浮提示框 →
tooltip - 底部滑块 →
dataZoom - 两侧颜色条 →
visualMap - 几张图表、分布在哪些网格中？→ 数出
grid数量，再确定对应的xAxis/yAxis数量
接着识别系列的数量与类型，最后补上数据与坐标轴绑定关系。大部分图表的 option 都可以通过这种方式还原出来。工具箱（toolbox）或 dataZoom 的联动配置可按需补充。
注意点
- 单个
grid内最多两个 x 轴和两个 y 轴，超出时需通过offset或增加新的grid。 series.data与dataset同时存在时，以series.data为准；treemap、graph 等图表不能使用dataset。- 动态数据更新通过再次调用
setOption完成，ECharts 会自动执行增量更新与动画过渡。对于百万级数据量，需使用appendData进行增量加载，但此方式不兼容dataset。 - 异步加载数据时，可以先
setOption显示空坐标轴与图例，待数据返回后再填入真实数据；等待期间可调用showLoading与hideLoading方法显示加载动画。 axisLabel.formatter可接收函数或字符串模板，对时间轴刻度格式化尤为方便。