ECharts 配置语法

ECharts 配置语法详解

Apache ECharts 的配置项（option）是图表的核心，使用纯 JSON 对象格式（JavaScript 对象字面量）。它采用声明式语法：你只需描述“图表应该长什么样”，ECharts 会自动渲染。

当前官方文档主要基于 ECharts 5.x 和 6.x（最新特性支持到 v6.0.0+），配置语法在 5.x 后相对稳定。

1. option 基本结构

一个典型的 option 对象结构如下：

var option = {
    // 全局配置
    backgroundColor: '#fff',  // 背景色
    color: ['#5470c6', '#91cc75', '#fac858', ...],  // 全局调色盘（系列自动取色）

    // 组件配置（可多个）
    title: { ... },       // 标题
    legend: { ... },      // 图例
    tooltip: { ... },     // 提示框
    toolbox: { ... },     // 工具箱
    grid: { ... },        // 直角坐标系网格
    xAxis: { ... },       // X 轴
    yAxis: { ... },       // Y 轴
    visualMap: { ... },   // 视觉映射
    dataZoom: { ... },    // 数据缩放

    // 数据系列（核心，必填，至少一个）
    series: [
        {
            type: 'bar',      // 图表类型
            name: '系列1',
            data: [10, 20, 30],
            itemStyle: { ... },  // 图形样式
            label: { ... },      // 数据标签
            emphasis: { ... }    // 高亮样式（悬停时）
        },
        // ... 更多系列
    ],

    // 其他高级配置
    media: [ ... ],       // 响应式配置
    animation: true       // 动画开关
};

2. 配置规则与语法要点

• 层级嵌套：配置项采用树状结构，子属性独立配置。例如 title.textStyle.color 只影响标题文本颜色。
• 合并与覆盖：
• 同层级重复属性，后者覆盖前者。
• 对象合并：子属性不会整体覆盖，而是逐个合并（例如修改 textStyle.fontSize 不会影响其他 textStyle 属性）。
• 系列 > 组件 > 全局 的优先级（局部覆盖全局）。
• 数组支持多实例：如 title: [{...}, {...}] 可显示多个标题；series 天然支持多个。
• 函数支持：许多属性支持函数形式，用于动态计算。例如：

  tooltip: {
      formatter: function (params) {
          return '值: ' + params.value;
      }
  }

• 富文本（Rich Text）：在文本属性（如 title.text、label.formatter）中使用 {style|文本} 语法，结合 rich 对象定义复杂样式。

  label: {
      formatter: '{a|富文本}\n{c|值: {c}}',
      rich: {
          a: { color: 'red', fontSize: 16 },
          c: { backgroundColor: '#eee', padding: 5 }
      }
  }

• 响应式配置（media query）：

  media: [
      {
          query: { maxWidth: 600 },  // 小屏幕
          option: { grid: { left: 20 }, series: [{ itemStyle: { ... } }] }
      },
      {
          option: { ... }  // 默认大屏幕配置
      }
  ]

3. 样式配置语法（常见）

ECharts 样式设置非常灵活，主要通过以下方式：

• 调色盘：根级 color 数组，或系列级 color。
• 直接样式（推荐扁平写法，ECharts 4+ 不强制用 normal）：

  series: [{
      itemStyle: {       // 柱子/点样式
          color: '#5470c6',              // 纯色
          borderColor: '#000',
          borderWidth: 2,
          shadowBlur: 10,
          shadowColor: 'rgba(0,0,0,0.3)'
      },
      lineStyle: { ... },   // 折线样式
      areaStyle: { ... },   // 区域填充
      label: {              // 数据标签
          show: true,
          color: '#fff',
          fontSize: 12
      },
      emphasis: {           // 鼠标悬停高亮
          itemStyle: { opacity: 0.8 },
          label: { show: true }
      }
  }]

• 渐变色/纹理：

  color: {
      type: 'linear',
      x: 0, y: 0, x2: 1, y2: 0,
      colorStops: [{ offset: 0, color: 'red' }, { offset: 1, color: 'blue' }]
  }

• 主题与视觉映射：通过 echarts.init(dom, 'dark') 切换主题，或用 visualMap 根据数据映射颜色/大小。

4. 学习建议

• 官方配置手册（最权威）：https://echarts.apache.org/zh/option.html （完整列出所有配置项）
• 示例 Gallery：https://echarts.apache.org/examples/zh/ （上千个可复制示例，直接查看 option）
• 速查手册：https://echarts.apache.org/zh/cheat-sheet.html （快速定位组件文档）

掌握配置语法的最佳方式是多看官方示例 + 改代码实践。如果你有特定组件（如 tooltip、series）的配置需求，或者想看某个图表的完整 option 示例，随时告诉我！