ECharts 安装与配置 #

本章将介绍 ECharts 的各种安装方式和环境配置，帮助你快速搭建开发环境。

安装方式 #

ECharts 提供了多种安装方式，你可以根据项目需求选择合适的方式：

text

┌─────────────────────────────────────────────────────────────┐
│                     安装方式选择                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  CDN 引入 ──────► 快速原型、简单项目                         │
│                                                              │
│  npm 安装 ──────► 现代 Web 项目、需要构建工具                │
│                                                              │
│  下载文件 ──────► 离线环境、需要完全控制                     │
│                                                              │
│  在线定制 ──────► 按需打包、减小文件体积                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

CDN 引入 #

直接引入 #

最简单的方式是使用 CDN 引入：

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>ECharts 示例</title>
  <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
</head>
<body>
  <div id="chart" style="width: 600px; height: 400px;"></div>
  <script>
    const chart = echarts.init(document.getElementById('chart'));
    chart.setOption({
      title: { text: 'ECharts 示例' },
      xAxis: { data: ['A', 'B', 'C'] },
      yAxis: {},
      series: [{ type: 'bar', data: [10, 20, 30] }]
    });
  </script>
</body>
</html>

常用 CDN 地址 #

CDN 提供商	地址
jsDelivr	`https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js`
unpkg	`https://unpkg.com/echarts@5/dist/echarts.min.js`
cdnjs	`https://cdnjs.cloudflare.com/ajax/libs/echarts/5/echarts.min.js`
bootcdn	`https://cdn.bootcdn.net/ajax/libs/echarts/5/echarts.min.js`

版本选择 #

html

<!-- 最新版本 -->
<script src="https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js"></script>

<!-- 指定版本 -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>

<!-- 开发版本（包含调试信息） -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.js"></script>

npm 安装 #

安装命令 #

bash

# npm
npm install echarts

# yarn
yarn add echarts

# pnpm
pnpm add echarts

项目中使用 #

完整引入 #

javascript

import * as echarts from 'echarts';

const chart = echarts.init(document.getElementById('chart'));
chart.setOption({
  // 配置项
});

按需引入 #

javascript

// 引入核心模块
import * as echarts from 'echarts/core';

// 引入图表类型
import { BarChart, LineChart, PieChart } from 'echarts/charts';

// 引入组件
import {
  TitleComponent,
  TooltipComponent,
  LegendComponent,
  GridComponent
} from 'echarts/components';

// 引入渲染器
import { CanvasRenderer } from 'echarts/renderers';

// 注册组件
echarts.use([
  BarChart,
  LineChart,
  PieChart,
  TitleComponent,
  TooltipComponent,
  LegendComponent,
  GridComponent,
  CanvasRenderer
]);

// 创建图表
const chart = echarts.init(document.getElementById('chart'));

按需引入完整示例 #

javascript

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

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

const chart = echarts.init(document.getElementById('chart'));
chart.setOption({
  title: { text: '柱状图示例' },
  tooltip: {},
  xAxis: { data: ['A', 'B', 'C'] },
  yAxis: {},
  series: [{ type: 'bar', data: [10, 20, 30] }]
});

TypeScript 支持 #

ECharts 提供了完整的 TypeScript 类型定义：

typescript

import * as echarts from 'echarts';
import type { EChartsOption } from 'echarts';

const chart = echarts.init(document.getElementById('chart') as HTMLDivElement);

const option: EChartsOption = {
  title: { text: 'TypeScript 示例' },
  xAxis: { type: 'category', data: ['A', 'B', 'C'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [10, 20, 30] }]
};

chart.setOption(option);

下载安装 #

下载地址 #

从以下地址下载 ECharts：

GitHub Releases: https://github.com/apache/echarts/releases
Apache 官方: https://echarts.apache.org/zh/download.html

文件结构 #

text

echarts/
├── dist/
│   ├── echarts.min.js        # 压缩版本
│   ├── echarts.js            # 未压缩版本
│   ├── echarts.common.min.js # 常用版本
│   └── echarts.common.js
├── lib/                       # 按需引入文件
└── extension/                 # 扩展组件

本地引入 #

html

<script src="./echarts/dist/echarts.min.js"></script>

在线定制 #

为什么需要定制？ #

text

┌─────────────────────────────────────────────────────────────┐
│                     在线定制的优势                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. 减小文件体积 - 只包含需要的图表和组件                    │
│                                                              │
│  2. 提高加载速度 - 更小的文件意味着更快的加载                │
│                                                              │
│  3. 优化性能 - 减少不必要的代码解析和执行                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

定制步骤 #

访问在线定制页面：https://echarts.apache.org/zh/builder.html
选择需要的组件：

text

┌─────────────────────────────────────────┐
│            选择图表类型                  │
├─────────────────────────────────────────┤
│  ☑ 柱状图 (bar)                         │
│  ☑ 折线图 (line)                        │
│  ☑ 饼图 (pie)                           │
│  ☐ 散点图 (scatter)                     │
│  ☐ 地图 (map)                           │
│  ☐ ...                                  │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│            选择组件                      │
├─────────────────────────────────────────┤
│  ☑ 标题 (title)                         │
│  ☑ 提示框 (tooltip)                     │
│  ☑ 图例 (legend)                        │
│  ☑ 坐标系 (grid)                        │
│  ☐ 数据区域缩放 (dataZoom)              │
│  ☐ ...                                  │
└─────────────────────────────────────────┘

点击下载，获取定制后的文件

框架集成 #

Vue 3 集成 #

安装 #

bash

npm install echarts vue-echarts

使用 #

vue

<template>
  <v-chart :option="chartOption" style="height: 400px" />
</template>

<script setup>
import { ref } from 'vue';
import VChart from 'vue-echarts';
import { use } from 'echarts/core';
import { CanvasRenderer } from 'echarts/renderers';
import { BarChart } from 'echarts/charts';
import { GridComponent, TooltipComponent } from 'echarts/components';

use([CanvasRenderer, BarChart, GridComponent, TooltipComponent]);

const chartOption = ref({
  xAxis: { type: 'category', data: ['A', 'B', 'C'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [10, 20, 30] }]
});
</script>

React 集成 #

安装 #

bash

npm install echarts echarts-for-react

使用 #

jsx

import ReactECharts from 'echarts-for-react';

function App() {
  const option = {
    xAxis: { type: 'category', data: ['A', 'B', 'C'] },
    yAxis: { type: 'value' },
    series: [{ type: 'bar', data: [10, 20, 30] }]
  };

  return (
    <ReactECharts
      option={option}
      style={{ height: 400 }}
    />
  );
}

Angular 集成 #

安装 #

bash

npm install echarts ngx-echarts

使用 #

typescript

import { Component } from '@angular/core';
import * as echarts from 'echarts';

@Component({
  selector: 'app-chart',
  template: '<div echarts [options]="chartOption" style="height: 400px"></div>'
})
export class ChartComponent {
  chartOption = {
    xAxis: { type: 'category', data: ['A', 'B', 'C'] },
    yAxis: { type: 'value' },
    series: [{ type: 'bar', data: [10, 20, 30] }]
  };
}

开发工具配置 #

VS Code 配置 #

安装 ECharts 智能提示插件：

text

扩展名称: echarts-vscode-extension
发布者: susan

Webpack 配置 #

javascript

module.exports = {
  resolve: {
    alias: {
      echarts: path.resolve('./node_modules/echarts')
    }
  }
};

Vite 配置 #

javascript

import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    include: ['echarts']
  }
});

基本使用模板 #

HTML 模板 #

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>ECharts 项目</title>
  <style>
    #chart {
      width: 100%;
      height: 400px;
    }
  </style>
</head>
<body>
  <div id="chart"></div>
  
  <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
  <script>
    // 初始化图表
    const chart = echarts.init(document.getElementById('chart'));
    
    // 配置项
    const option = {
      title: {
        text: 'ECharts 示例'
      },
      tooltip: {
        trigger: 'axis'
      },
      xAxis: {
        type: 'category',
        data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
      },
      yAxis: {
        type: 'value'
      },
      series: [{
        name: '销量',
        type: 'line',
        data: [120, 200, 150, 80, 70, 110, 130]
      }]
    };
    
    // 应用配置
    chart.setOption(option);
    
    // 响应式
    window.addEventListener('resize', () => {
      chart.resize();
    });
  </script>
</body>
</html>

ES Module 模板 #

javascript

import * as echarts from 'echarts';

class ChartManager {
  constructor(container) {
    this.chart = echarts.init(container);
    this.setupResize();
  }
  
  setOption(option) {
    this.chart.setOption(option);
  }
  
  setupResize() {
    window.addEventListener('resize', () => {
      this.chart.resize();
    });
  }
  
  dispose() {
    this.chart.dispose();
  }
}

// 使用
const manager = new ChartManager(document.getElementById('chart'));
manager.setOption({
  // 配置项
});

常见问题 #

1. 图表不显示 #

检查以下几点：

javascript

// 1. 确保容器有高度
const container = document.getElementById('chart');
console.log(container.offsetHeight); // 应该 > 0

// 2. 确保正确初始化
const chart = echarts.init(container);
console.log(chart); // 应该是 echarts 实例

// 3. 确保配置正确
chart.setOption(option);

2. 按需引入后图表不显示 #

确保注册了所有需要的组件：

javascript

import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { GridComponent } from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';

// 必须注册所有需要的组件
echarts.use([
  BarChart,
  GridComponent,
  CanvasRenderer
]);

3. 响应式问题 #

javascript

// 正确的响应式处理
const chart = echarts.init(container);

window.addEventListener('resize', () => {
  chart.resize();
});

// 或使用 ResizeObserver
const observer = new ResizeObserver(() => {
  chart.resize();
});
observer.observe(container);

下一步 #

现在你已经完成了环境搭建，接下来学习基础概念，了解 ECharts 的核心配置！