安装与配置
选择合适的安装方式，正确配置开发环境
📦 安装方式对比
1. CDN引入(最简单)
适用场景: 快速原型、简单项目、学习测试
html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<!-- 完整引入 -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
</head>
<body>
<div id="main" style="width: 600px;height:400px;"></div>
<script>
var chart = echarts.init(document.getElementById('main'));
chart.setOption({ /* ... */ });
</script>
</body>
</html>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
CDN选择:
html
<!-- jsDelivr (推荐) -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
<!-- unpkg -->
<script src="https://unpkg.com/echarts@5.4.3/dist/echarts.min.js"></script>
<!-- 国内加速 - 阿里云CDN -->
<script src="https://cdn.bootcdn.net/ajax/libs/echarts/5.4.3/echarts.min.js"></script>1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
优缺点:
- ✅ 优点: 零配置、无需构建工具
- ❌ 缺点: 无法Tree Shaking、包体积大(约900KB)
2. NPM安装(推荐)
适用场景: Vue/React项目、工程化开发
bash
npm install echarts
# 或
yarn add echarts
# 或
pnpm add echarts1
2
3
4
5
2
3
4
5
基本使用:
javascript
import * as echarts from 'echarts';
const chart = echarts.init(document.getElementById('main'));
chart.setOption({
xAxis: { data: ['A', 'B', 'C'] },
yAxis: {},
series: [{ type: 'bar', data: [1, 2, 3] }]
});1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
优缺点:
- ✅ 优点: 版本管理、支持Tree Shaking
- ⚠️ 注意: 默认引入完整包，需手动按需引入减小体积
3. 按需引入(最佳实践)
适用场景: 生产环境、对包体积敏感的项目
javascript
// 引入核心模块
import * as echarts from 'echarts/core';
// 按需引入图表类型
import { BarChart, LineChart } from 'echarts/charts';
// 按需引入组件
import {
TitleComponent,
TooltipComponent,
GridComponent
} from 'echarts/components';
// 按需引入渲染器
import { CanvasRenderer } from 'echarts/renderers';
// 注册必须的组件
echarts.use([
TitleComponent,
TooltipComponent,
GridComponent,
BarChart,
LineChart,
CanvasRenderer
]);
// 初始化
const chart = echarts.init(document.getElementById('main'));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
包体积对比:
| 引入方式 | 压缩后大小 | Gzip后 |
|---|---|---|
| 完整引入 | ~900KB | ~270KB |
| 按需引入(折线图+柱状图) | ~150KB | ~50KB |
| 按需引入(仅饼图) | ~80KB | ~28KB |
优缺点:
- ✅ 优点: 最小化包体积、提升加载速度
- ❌ 缺点: 配置稍复杂、新增图表需重新注册
🔧 TypeScript配置
tsconfig.json配置
json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"strict": true
},
"include": ["src/**/*.ts", "src/**/*.d.ts"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
类型定义
ECharts自带TypeScript类型定义，无需额外安装：
typescript
import * as echarts from 'echarts';
import type { EChartsOption } from 'echarts';
// 完整的类型提示
const option: EChartsOption = {
title: { text: '示例' },
xAxis: { type: 'category', data: ['A', 'B'] },
yAxis: { type: 'value' },
series: [{ type: 'bar', data: [1, 2] }]
};
const chart = echarts.init(document.getElementById('main')!);
chart.setOption(option);1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
🎨 主题配置
内置主题
ECharts提供两个内置主题：
light(默认)dark
javascript
// 使用暗色主题
const chart = echarts.init(dom, 'dark');1
2
2
自定义主题
方法1: 在线主题编辑器
访问 ECharts主题编辑器 可视化定制主题
方法2: 代码定义主题
javascript
echarts.registerTheme('my-theme', {
backgroundColor: '#f4cccc',
color: ['#c23531','#2f4554', '#61a0a8'],
title: {
textStyle: {
fontSize: 18,
fontWeight: 'bold',
color: '#333'
}
},
categoryAxis: {
axisLine: { lineStyle: { color: '#333' } },
splitLine: { lineStyle: { color: ['#ddd'] } }
}
});
const chart = echarts.init(dom, 'my-theme');1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
方法3: JSON主题文件
javascript
// 加载JSON主题
fetch('/themes/my-theme.json')
.then(res => res.json())
.then(theme => {
echarts.registerTheme('my-theme', theme);
const chart = echarts.init(dom, 'my-theme');
});1
2
3
4
5
6
7
2
3
4
5
6
7
🌍 国际化配置
切换语言
javascript
// 切换到英文
import * as echarts from 'echarts';
import 'echarts/i18n/langEN';
echarts.setLocale('EN');
// 切换到中文(默认)
echarts.setLocale('ZH');1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
支持的语言:
ZH- 中文(默认)EN- 英文DE- 德文FR- 法文JA- 日文RU- 俄文
自定义文本
javascript
echarts.setLocale({
time: {
month: [
'一月', '二月', '三月', '四月', '五月', '六月',
'七月', '八月', '九月', '十月', '十一月', '十二月'
]
},
toolbox: {
brush: {
title: {
rect: '框选',
polygon: '圈选',
lineX: '横向选择',
lineY: '纵向选择',
keep: '保持选择',
clear: '清除选择'
}
}
}
});1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
⚙️ 全局配置
默认选项设置
javascript
// 设置全局默认配置
echarts.registerPreprocessor(function (option) {
// 为所有图表添加默认标题样式
if (option.title && !option.title.textStyle) {
option.title.textStyle = {
fontSize: 16,
color: '#333'
};
}
});1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
渲染器配置
javascript
// 指定渲染器
const chart = echarts.init(dom, null, {
renderer: 'canvas', // 或 'svg'
devicePixelRatio: window.devicePixelRatio || 1,
width: 800,
height: 600
});1
2
3
4
5
6
7
2
3
4
5
6
7
Canvas vs SVG选择建议:
- Canvas: 大数据量(>1万)、动态更新频繁
- SVG: 小数据量、需要清晰缩放、静态展示
🚀 性能优化配置
设备像素比
javascript
// 高分屏优化
const dpr = window.devicePixelRatio || 1;
const chart = echarts.init(dom, null, {
devicePixelRatio: dpr
});1
2
3
4
5
2
3
4
5
防抖配置
javascript
// 窗口resize防抖
let resizeTimer;
window.addEventListener('resize', () => {
clearTimeout(resizeTimer);
resizeTimer = setTimeout(() => {
chart.resize();
}, 100);
});1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
📱 移动端适配
响应式配置
javascript
// 监听容器大小变化
const observer = new ResizeObserver(entries => {
for (let entry of entries) {
chart.resize();
}
});
observer.observe(container);1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
触摸事件优化
javascript
chart.setOption({
tooltip: {
trigger: 'item',
// 移动端优化
confine: true, // 限制在图表区域内
enterable: false
}
});1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
🐛 常见问题
Q1: 图表不显示？
检查清单:
- 容器是否有宽高？
- 是否在DOM加载完成后初始化？
- 控制台是否有报错？
- option配置是否正确？
javascript
// 确保容器有宽高
<div id="main" style="width: 100%; height: 400px;"></div>
// DOM加载完成后初始化
window.addEventListener('DOMContentLoaded', () => {
const chart = echarts.init(document.getElementById('main'));
});1
2
3
4
5
6
7
2
3
4
5
6
7
Q2: 打包体积过大？
解决方案:
- 使用按需引入
- 启用Tree Shaking
- 检查是否重复引入
javascript
// webpack配置
module.exports = {
optimization: {
usedExports: true, // Tree Shaking
sideEffects: false
}
};1
2
3
4
5
6
7
2
3
4
5
6
7
Q3: TypeScript类型错误？
解决方案:
- 确保安装了最新版本的echarts
- 检查tsconfig.json配置
- 使用类型断言
typescript
// 类型断言
const chart = echarts.init(document.getElementById('main') as HTMLDivElement);1
2
2
📚 下一步
祝你使用愉快！🎉