ECharts 配置项的用法（echarts setoption）

掌握 ECharts 配置项的用法，就等于掌握了 ECharts 的 90%。下面我将为你详细介绍 ECharts 配置项（option 对象）的一般用法，从核心概念到主要组件，再到数据格式和最佳实践。

一、 核心概念：声明式的“图表配方”

ECharts 的核心设计哲学是声明式（Declarative）。你不需要用代码去一步步“画”图表（比如“画一个X轴，再画一个Y轴，然后循环数据画柱子”），而是提供一个配置对象 option，像一个“配方”或“蓝图”一样，声明你想要一个什么样的图表。ECharts 会根据这个“配方”自动为你渲染出最终的图表。

这个核心 option 对象就是所有魔法的起点。

Generated javascript

// 1. 初始化一个 ECharts 实例

var myChart = echarts.init(document.getElementById('main'));

// 2. 准备一个配置对象 (option)

var option = {

// ... 这里就是图表的“配方”

};

// 3. 将配置应用到图表实例上

myChart.setOption(option);

二、option 对象的核心结构

一个典型的 option 对象由多个**组件（Component）**构成。每个组件都是 option 的一个顶级属性，负责图表的某一部分功能。

以下是几乎所有图表都会用到的几个核心组件：

组件名功能描述好比是...

title图表的标题和副标题。文章的标题

legend图例，用于筛选和区分不同的数据系列。地图的图例说明

grid网格/绘图区，定义了图表主体的位置和大小。画布的画框

xAxisX轴，定义了直角坐标系的横轴。图表的横坐标

yAxisY轴，定义了直角坐标系的纵轴。图表的纵坐标

tooltip提示框，鼠标悬浮在数据上时显示详细信息。数据的浮动说明书

series数据系列，是图表数据的核心，决定图表类型。图表的灵魂和血肉

toolbox工具箱，提供下载、缩放、切换图表等功能。图表的瑞士军刀

三、主要组件的详细用法

1. title - 标题组件

Generated javascript

title: {

text: '我的第一个 ECharts 图表', // 主标题

subtext: '数据来源：模拟数据', // 副标题

left: 'center', // 水平对齐方式: 'left', 'center', 'right'

top: 'top', // 垂直对齐方式: 'top', 'middle', 'bottom'

textStyle: { // 主标题样式

color: '#333',

fontSize: 18

}

}

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

2. legend - 图例组件

图例的 data 需要和 series 中每个系列的 name 对应起来，才能实现点击图例控制系列显示/隐藏的功能。

Generated javascript

legend: {

data: ['销量', '利润'], // 这里的名字要和 series 里的 name 匹配

left: 'left'

}

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

3. grid - 绘图区组件

grid 定义了柱状图、折线图等主体内容绘制的区域。调整它可以给坐标轴标签、图例等留出空间。

Generated javascript

grid: {

left: '3%', // grid 区域离容器左侧的距离

right: '4%', // 离右侧的距离

bottom: '3%', // 离底部的距离

containLabel: true // 这个属性很重要，设为 true 可以防止坐标轴标签溢出

}

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

4. xAxis & yAxis - 坐标轴组件

它们可以是数组（用于创建多个坐标轴），但通常情况下是对象。

type: 坐标轴类型

'category': 类目轴，适用于离散的数据，如“周一”、“周二”。data 属性用来指定类目。

'value': 数值轴，适用于连续的数据。

'time': 时间轴。

'log': 对数轴。

Generated javascript

// X 轴 - 通常是类目

xAxis: {

type: 'category',

data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子'] // 类目数据

},

// Y 轴 - 通常是数值

yAxis: {

type: 'value',

name: '单位: 件' // Y轴名称

}

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

5. tooltip - 提示框组件

tooltip 负责交互体验，配置非常灵活。

Generated javascript

tooltip: {

trigger: 'axis', // 触发类型: 'item' (数据项), 'axis' (坐标轴), 'none'

axisPointer: { // 坐标轴指示器配置

type: 'shadow' // 'line', 'shadow', 'cross'

},

// formatter: 可以用来自定义提示框内容，非常强大

formatter: function (params) {

// params 是一个包含当前系列信息的数组

let res = params[0].name + '<br/>';

params.forEach(item => {

res += item.marker + item.seriesName + ': ' + item.value + '<br/>';

});

return res;

}

}

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

6. series - 数据系列组件 (最核心)

series 是一个数组，数组中的每一个对象都代表一个数据系列。你可以在一个图表中混合多种类型的系列，比如同时展示柱状图和折线图。

每个系列对象至少需要包含 type 和 data。

type: 定义了图表的类型，如 'bar' (柱状图), 'line' (折线图), 'pie' (饼图), 'scatter' (散点图) 等。

name: 系列名称，用于 legend 和 tooltip 的显示。

data: 系列的数据。

其他常用配置:

itemStyle: 图形的样式（如柱子的颜色、边框）。

label: 数据标签的配置。

smooth: 在折线图中，设为 true 可使线条平滑。

stack: 数据堆叠，用于创建堆叠柱状图/面积图。

Generated javascript

series: [

// 第一个系列：柱状图

{

name: '销量',

type: 'bar',

data: [5, 20, 36, 10, 10, 20]

},

// 第二个系列：折线图

{

name: '利润',

type: 'line',

data: [15, 30, 46, 20, 25, 30],

smooth: true

}

]

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

四、如何组织数据

ECharts 提供了两种主要的数据组织方式。

方式一：直接在 series.data 中定义 (简单直观)

这是最基础的方式，适合简单图表。

Generated javascript

series: [{

type: 'bar',

// 1D 数组，值与 xAxis 的类目一一对应

data: [120, 200, 150, 80, 70, 110, 130]

}]

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

对于饼图、散点图等，data 通常是对象数组：

Generated javascript

series: [{

type: 'pie',

// 对象数组，每个对象包含 value 和 name

data: [

{ value: 1048, name: '搜索引擎' },

{ value: 735, name: '直接访问' },

{ value: 580, name: '邮件营销' }

]

}]

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

方式二：使用 dataset 组件 (推荐的最佳实践)

从 ECharts 4 开始，引入了 dataset 组件，它实现了数据与样式的分离。这是一种更现代、更强大的方式。

优点：

数据复用：一份数据可以被多个系列复用。

配置清晰：series 中不再需要包含大段的数据，配置项更简洁。

数据映射灵活：可以通过 encode 轻松地将数据的不同维度（列）映射到图表的不同部分（如 X 轴、Y 轴、气泡大小等）。

用法：

在 option 的顶层定义 dataset，并提供 source 数据。

在 series 中，不再写 data，而是通过 encode 来声明如何从 dataset 中取数据。

Generated javascript

option = {

// ... 其他组件 ...

dataset: {

// source 是一个二维数组，第一行通常是表头

source: [

['product', '2015', '2016', '2017'],

['Matcha Latte', 43.3, 85.8, 93.7],

['Milk Tea', 83.1, 73.4, 55.1],

['Cheese Cocoa', 86.4, 65.2, 82.5],

['Walnut Brownie', 72.4, 53.9, 39.1]

]

},

xAxis: { type: 'category' },

yAxis: {},

series: [

{

type: 'bar',

// encode 定义了如何映射

encode: {

x: 'product', // 'product' 列映射到 X 轴

y: '2015' // '2015' 列映射到 Y 轴

}

},

{

type: 'bar',

encode: {

x: 'product',

y: '2016'

}

}

]

}

IGNORE_WHEN_COPYING_START

content_copy

download

Use code with caution.

JavaScript

IGNORE_WHEN_COPYING_END

五、最佳实践与学习建议

官方文档是最好的老师：ECharts 的官方文档极其详尽，尤其是配置项手册和示例页面。遇到不确定的配置，第一时间查阅文档。

配置项手册:
https://echarts.apache.org/zh/option.html

从示例开始：直接从官方示例中找到一个与你需求最接近的图表，修改它的 option 是最快的上手方式。

善用 dataset：对于复杂或需要多系列复用数据的图表，强烈建议使用 dataset，它会让你的配置更清晰、更易于维护。

由简到繁：先构建一个最基本的图表（只有 xAxis, yAxis, series），确保数据显示正确，然后再逐步添加 title, legend, tooltip 等美化和交互组件。

检查浏览器控制台：如果图表没有按预期显示，打开浏览器的开发者工具（F12），ECharts 经常会在控制台打印出有用的警告信息，比如配置项错误或数据格式问题。

掌握了以上这些核心组件和数据组织方式，你就已经具备了创建绝大多数常见图表的能力。剩下的就是通过实践和查阅文档，去探索 ECharts 更多高级和有趣的配置了。