Apache ECharts 配置参数详解

详解 Apache ECharts 的初始化参数（renderer、ssr 等）与 option 配置（title、tooltip、legend、grid、坐标轴、series、dataset、visualMap、theme）及按需引入。

Apache EChartsApache ECharts2026/10/12

Apache ECharts 配置参数详解

实测环境：Ubuntu 22.04.5 LTS / CentOS Linux 8，ECharts 6.1.0，Node.js 18.20.8。示例回显为真实运行结果。

一、配置体系概述

ECharts 的配置分为两层：

  • init 初始化参数：决定「在哪里、用什么渲染器、多大尺寸、是否 SSR」绘制，属于实例级设置。
  • option 数据配置：决定「画什么」，即标题、坐标轴、系列数据、视觉映射等，属于图表级设置。

典型调用：

const chart = echarts.init(null, null, { renderer: 'svg', ssr: true, width: 800, height: 400 });
chart.setOption({ /* option 配置 */ });

二、init 初始化参数详解

echarts.init(dom, theme, opts) 的第三个参数 opts 支持以下字段。

2.1 renderer

渲染器类型，取值 'canvas'（默认）或 'svg'。

  • 'canvas'：以像素位图绘制，海量图形（数万个数据点）时性能更佳，导出 PNG 更方便。
  • 'svg'：以矢量标签绘制，缩放不失真，适合服务端 SSR 与截图打印。
echarts.init(null, null, { renderer: 'svg', ssr: true, width: 800, height: 400 });

2.2 devicePixelRatio

设备像素比。Canvas 渲染下用于高清屏防模糊，默认取浏览器 window.devicePixelRatio。SSR 场景可显式指定，例如 devicePixelRatio: 2 生成两倍图。

2.3 ssr

布尔值，是否为服务端渲染模式。为 true 时可在无 DOM 环境（Node.js）中初始化并在服务端出图：

const chart = echarts.init(null, null, { renderer: 'svg', ssr: true, width: 800, height: 400 });
const svg = chart.renderToSVGString();

注意：renderToSVGString() 仅在 renderer:'svg' 且 ssr:true 时可用；Canvas SSR 需借助 canvas 包并通过 getDataURL() 导出。

2.4 width / height

实例宽高（像素）。SSR 模式无 DOM 尺寸可测量，必须显式给出 width 与 height，否则渲染为 0。

2.5 locale

语言区域，影响内置文案（如工具箱提示）。取值如 'ZH'（中文）、'EN'（英文），默认 'EN'。

2.6 theme

主题名或主题对象，作为 init 的第二个参数传入：echarts.init(dom, 'dark', opts)。内置主题有 'dark'，也可传入注册好的自定义主题对象。

三、option 顶层配置项

3.1 title

标题组件，可配置主标题 text、副标题 subtext、位置 left/top/right/bottom 与样式 textStyle。

title: { text: '月度销量', subtext: '单位：万件', left: 'center' }

3.2 tooltip

提示框组件，trigger 决定触发方式：'item'（数据项，适用于饼图/散点图）、'axis'（坐标轴，适用于柱状图/折线图）、'none'（不触发）。formatter 可自定义内容。

tooltip: { trigger: 'axis' }

3.3 legend

图例组件，data 指定显示哪些系列名，可多选切换。orient 为 'horizontal'（默认）或 'vertical'。

legend: { data: ['访问量', '下单量'], top: 'bottom' }

3.4 grid

直角坐标系网格，控制绘图区边距：left/right/top/bottom 支持像素或百分比，containLabel 为 true 时自动计算坐标轴标签占位。

grid: { left: 40, right: 20, top: 50, bottom: 30, containLabel: true }

3.5 xAxis

直角坐标系 X 轴。type 取值 'category'（类目轴，配 data 使用）、'value'（数值轴）、'time'（时间轴）、'log'（对数轴）。

xAxis: { type: 'category', data: ['1月','2月','3月','4月'] }

3.6 yAxis

直角坐标系 Y 轴，字段与 xAxis 对称。柱状图/折线图常设 type: 'value'。

yAxis: { type: 'value', name: '销量' }

3.7 series

系列数组，是图表主体。type 决定图表类型：'bar'（柱状）、'line'（折线）、'pie'（饼图）、'scatter'（散点）等。name 对应图例名，data 为数据数组。

series: [
  { name: '销量', type: 'bar', data: [120, 200, 150, 80] },
  { name: '增速', type: 'line', smooth: true, data: [10, 15, 8, 12] }
]

3.8 dataset

数据集组件，把「数据」与「系列」解耦，推荐用于多图表复用同一份数据。配合 series.encode 指定维度映射。

dataset: {
  source: [
    ['月份', '销量', '增速'],
    ['1月', 120, 10],
    ['2月', 200, 15]
  ]
},
xAxis: { type: 'category' },
yAxis: { type: 'value' },
series: [
  { type: 'bar', encode: { x: '月份', y: '销量' } },
  { type: 'line', encode: { x: '月份', y: '增速' } }
]

3.9 visualMap

视觉映射组件，把数据值映射到颜色、尺寸等视觉通道。type 为 'continuous'（连续）或 'piecewise'（分段）。

visualMap: { type: 'continuous', min: 0, max: 200, calculable: true, inRange: { color: ['#50a3ba', '#eac763', '#d94e5d'] } }

四、按需引入（echarts/core + use）

全量引入 import * as echarts from 'echarts' 体积较大。生产项目可按需引入核心与组件，减小打包体积：

import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { TitleComponent, TooltipComponent, GridComponent } from 'echarts/components';
import { SVGRenderer } from 'echarts/renderers';

echarts.use([BarChart, TitleComponent, TooltipComponent, GridComponent, SVGRenderer]);

规则：用到哪种 series.type 就注册对应图表（BarChart/LineChart/PieChart），用到哪个组件就注册哪个（LegendComponent/VisualMapComponent 等），渲染器按 SVGRenderer 或 CanvasRenderer 二选一。

真实运行回显：

node ondemand.mjs
# 回显：按需引入 SVG 长度=5071 文件大小=5085
#       echarts version = 6.1.0

五、完整配置示例

以下柱状图配置经真实 SSR 渲染，产出 5597 字节 SVG：

chart.setOption({
  title: { text: '各月访问量（柱状图）' },
  tooltip: { trigger: 'axis' },
  legend: { data: ['访问量'] },
  grid: { left: 40, right: 20, top: 50, bottom: 30 },
  xAxis: { type: 'category', data: ['1月','2月','3月','4月','5月','6月'] },
  yAxis: { type: 'value' },
  series: [{ name: '访问量', type: 'bar', data: [120, 200, 150, 80, 170, 230] }]
});

对应的饼图配置（实测 3932 字节 SVG）：

chart.setOption({
  title: { text: '流量来源占比（饼图）' },
  tooltip: { trigger: 'item' },
  series: [{
    name: '来源', type: 'pie', radius: '55%',
    data: [
      { value: 1048, name: '搜索引擎' },
      { value: 735, name: '直接访问' },
      { value: 580, name: '邮件营销' },
      { value: 484, name: '联盟广告' }
    ]
  }]
});

小结：init 管「怎么画」，option 管「画什么」；把握这两层即可覆盖绝大多数配置场景。