ECharts 速查手册

📋 概述

快速查阅ECharts常用配置、API和方法的速查手册，适合日常开发时快速参考。

---

🎯 快速开始

最小可用示例

import * as echarts from 'echarts';

const chart = echarts.init(document.getElementById('main'));
chart.setOption({
  xAxis: { type: 'category', data: ['A', 'B', 'C'] },
  yAxis: { type: 'value' },
  series: [{ data: [10, 20, 30], type: 'bar' }]
});

---

🔧 常用图表配置

折线图

{
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
  yAxis: { type: 'value' },
  series: [{
    data: [150, 230, 224],
    type: 'line',
    smooth: true,              // 平滑曲线
    symbol: 'circle',          // 数据点形状
    symbolSize: 8,             // 数据点大小
    lineStyle: { width: 2 },   // 线条样式
    areaStyle: {               // 面积图
      opacity: 0.3
    }
  }]
}

---

柱状图

{
  xAxis: { type: 'category', data: ['A', 'B', 'C'] },
  yAxis: { type: 'value' },
  series: [{
    data: [120, 200, 150],
    type: 'bar',
    barWidth: '60%',           // 柱子宽度
    itemStyle: {
      borderRadius: [5, 5, 0, 0] // 圆角
    }
  }]
}

---

饼图

{
  series: [{
    type: 'pie',
    radius: ['40%', '70%'],    // 环形图
    avoidLabelOverlap: false,
    data: [
      { value: 1048, name: 'Search Engine' },
      { value: 735, name: 'Direct' }
    ],
    label: {
      show: true,
      formatter: '{b}: {d}%'   // 显示百分比
    }
  }]
}

---

散点图

{
  xAxis: {},
  yAxis: {},
  series: [{
    type: 'scatter',
    data: [[10, 20], [30, 40], [50, 60]],
    symbolSize: 20,
    itemStyle: {
      color: '#5470c6'
    }
  }]
}

---

🎨 常用样式配置

颜色主题

// 方法1：使用内置主题
const chart = echarts.init(container, 'dark');

// 方法2：自定义配色
{
  color: ['#5470c6', '#91cc75', '#fac858', '#ee6666'],
  series: [{
    itemStyle: {
      color: '#5470c6'
    }
  }]
}

---

标题和图例

{
  title: {
    text: '主标题',
    subtext: '副标题',
    left: 'center',
    textStyle: { fontSize: 18 }
  },
  legend: {
    data: ['系列1', '系列2'],
    orient: 'vertical',        // 垂直排列
    right: 10,
    top: 'center'
  }
}

---

提示框（Tooltip）

{
  tooltip: {
    trigger: 'axis',           // 'item' | 'axis' | 'none'
    axisPointer: {
      type: 'cross'            // 'line' | 'shadow' | 'cross'
    },
    formatter: (params) => {
      return `${params[0].name}: ${params[0].value}`;
    }
  }
}

---

📐 布局配置

Grid（直角坐标系网格）

{
  grid: {
    left: '3%',
    right: '4%',
    bottom: '3%',
    top: '10%',
    containLabel: true         // 包含坐标轴标签
  }
}

---

DataZoom（数据区域缩放）

{
  dataZoom: [
    {
      type: 'slider',          // 滑动条
      start: 0,                // 起始百分比
      end: 100                 // 结束百分比
    },
    {
      type: 'inside',          // 内部缩放（鼠标滚轮）
      start: 0,
      end: 100
    }
  ]
}

---

🎭 动画配置

{
  animation: true,
  animationDuration: 1000,     // 动画时长（毫秒）
  animationEasing: 'cubicOut', // 缓动函数
  animationDelay: 0            // 延迟时间
}

常用缓动函数：

• linear
• cubicIn / cubicOut / cubicInOut
• elasticIn / elasticOut
• bounceIn / bounceOut

---

🖱️ 交互事件

事件绑定

// 点击事件
chart.on('click', (params) => {
  console.log(params.name, params.value);
});

// 悬停事件
chart.on('mouseover', (params) => {
  console.log('Hover:', params);
});

// 数据区域缩放
chart.on('datazoom', (params) => {
  console.log('Zoom:', params.start, params.end);
});

// 图例选择
chart.on('legendselectchanged', (params) => {
  console.log('Selected:', params.selected);
});

---

常用事件类型

事件名	触发时机
click	鼠标点击
dblclick	双击
mouseover	鼠标悬停
mouseout	鼠标移出
datazoom	数据缩放
legendselectchanged	图例选择变化
restore	重置
rendered	渲染完成

---

⚙️ 常用API

实例方法

// 设置/更新配置
chart.setOption(option, { notMerge: false });

// 调整大小
chart.resize({ width: 800, height: 600 });

// 获取配置
const option = chart.getOption();

// 导出图片
const url = chart.getDataURL({
  type: 'png',
  pixelRatio: 2,
  backgroundColor: '#fff'
});

// 下载图片
chart.saveAsImage({
  type: 'png',
  name: 'chart',
  pixelRatio: 2
});

// 清空图表
chart.clear();

// 销毁实例
chart.dispose();

// 显示加载动画
chart.showLoading({
  text: '加载中...',
  color: '#c23531',
  textColor: '#000',
  maskColor: 'rgba(255, 255, 255, 0.8)'
});

// 隐藏加载动画
chart.hideLoading();

---

静态方法

// 注册主题
echarts.registerTheme('my-theme', themeConfig);

// 注册地图
echarts.registerMap('china', chinaGeoJson);

// 注册图表类型
echarts.registerChart(type, clazz);

// 颜色工具
echarts.color.lift('#5470c6', 0.2);  // 提亮
echarts.color.darken('#5470c6', 0.2); // 变暗

---

🗺️ 地图配置

{
  geo: {
    map: 'china',
    roam: true,                  // 允许缩放拖拽
    zoom: 1.2,
    label: { show: true },
    itemStyle: {
      areaColor: '#eeeeee',
      borderColor: '#999999'
    },
    emphasis: {
      itemStyle: {
        areaColor: '#fe994e'
      }
    }
  },
  series: [{
    type: 'scatter',
    coordinateSystem: 'geo',
    data: [
      { name: '北京', value: [116.40, 39.90, 100] },
      { name: '上海', value: [121.47, 31.23, 150] }
    ]
  }]
}

---

🌈 视觉映射

{
  visualMap: {
    min: 0,
    max: 1000,
    calculable: true,            // 显示滑块
    orient: 'horizontal',
    left: 'center',
    bottom: '5%',
    inRange: {
      color: ['#e0f3f8', '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026']
    }
  }
}

---

📊 响应式配置

// 监听窗口变化
window.addEventListener('resize', () => {
  chart.resize();
});

// 使用媒体查询
const mediaQuery = window.matchMedia('(max-width: 768px)');
mediaQuery.addListener((e) => {
  if (e.matches) {
    // 移动端配置
    chart.setOption(mobileOption);
  } else {
    // 桌面端配置
    chart.setOption(desktopOption);
  }
});

---

🎯 按需引入清单

基础图表

import * as echarts from 'echarts/core';
import {
  LineChart,
  BarChart,
  PieChart,
  ScatterChart
} from 'echarts/charts';
import {
  GridComponent,
  TooltipComponent,
  LegendComponent,
  TitleComponent
} from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';

echarts.use([
  LineChart,
  BarChart,
  PieChart,
  ScatterChart,
  GridComponent,
  TooltipComponent,
  LegendComponent,
  TitleComponent,
  CanvasRenderer
]);

---

高级图表

import {
  HeatmapChart,
  MapChart,
  RadarChart,
  GaugeChart,
  FunnelChart,
  SankeyChart,
  GraphChart,
  TreeChart,
  TreemapChart,
  BoxplotChart,
  CandlestickChart
} from 'echarts/charts';

---

💻 TypeScript类型

import type {
  EChartsOption,
  LineSeriesOption,
  BarSeriesOption,
  PieSeriesOption,
  XAXisOption,
  YAXisOption
} from 'echarts';

// 使用示例
const option: EChartsOption = {
  // ... 配置
};

const lineOption: LineSeriesOption = {
  type: 'line',
  data: [1, 2, 3]
};

---

🔍 调试技巧

1. 检查配置

// 在浏览器控制台
console.log(chart.getOption());

---

2. 性能分析

// 开启性能监控
echarts.init(container, null, {
  renderer: 'canvas',
  devicePixelRatio: window.devicePixelRatio
});

// 查看渲染时间
performance.mark('chart-start');
chart.setOption(option);
performance.mark('chart-end');
performance.measure('chart-render', 'chart-start', 'chart-end');
console.log(performance.getEntriesByName('chart-render'));

---

3. 内存泄漏检测

// 确保正确销毁
componentWillUnmount() {
  chart.dispose();
  chart = null;
}

// 检查实例数量
console.log(echarts.getInstanceByDom(container));

---

⚡ 性能优化速查

优化项	方法	效果
Bundle体积	按需引入	↓ 80%
大数据量	sampling: 'lttb'	↑ 10倍
频繁更新	throttle/debounce	↓ CPU 50%
多个图表	虚拟滚动	↓ 内存 70%
动画性能	animation: false	↑ FPS 20

---

🆘 常见问题

Q1: 图表不显示？

// 检查容器尺寸
console.log(container.clientWidth, container.clientHeight);

// 确保调用resize
setTimeout(() => chart.resize(), 0);

---

Q2: 数据更新不生效？

// 使用notMerge强制合并
chart.setOption(newOption, { notMerge: true });

---

Q3: 中文乱码？

// 确保HTML编码
<meta charset="UTF-8">

// 或在配置中指定
{
  textStyle: {
    fontFamily: 'Microsoft YaHei'
  }
}

---

📚 更多资源

• 官方文档: https://echarts.apache.org/zh/option.html
• 示例库: https://echarts.apache.org/examples/zh/index.html
• 社区论坛: https://github.com/apache/echarts/discussions

---

提示：本速查手册涵盖80%的常用配置，详细配置请参考官方文档。