做课程报告的时候，对着 Excel 里一堆冷冰冰的数字真的头大 —— 小组展示时光念数据，底下同学都快听困了，老师还问 “能不能直观一点？” 😫 直到我发现了ECharts这个宝藏工具！柱状图、饼图随便搞，数据秒变炫酷图表，上次展示直接被老师夸 “有想法”，太爽了～
今天就跟大家分享怎么在 React + TypeScript 项目里用 ECharts，从装依赖到画出第一个图，全程保姆级教程，小白也能学会！💻
为什么选 ECharts？
ECharts 是百度开源的数据可视化库，能轻松实现：
- 2D 图表（柱状、饼状、折线、雷达图等）；
- 交互能力（hover 提示、点击筛选、缩放平移）；
- 响应式布局（适配不同屏幕尺寸）；
- 海量示例（官网示例库直接抄作业🤩）。
无论是 “业务报表”“数据大屏” 还是 “用户行为分析”，ECharts 都能把数据 “可视化翻译” 成人人能懂的图表～
React + TS 项目中集成 ECharts：三步搞定
步骤 1：安装依赖（别漏了类型声明！）
首先执行命令安装核心库和 TypeScript 类型声明：
npm install echarts @types/echarts
这里要注意：
echarts是核心库（纯 JS 编写，负责绘图逻辑）；@types/echarts是类型声明文件（给 TS 用的，让代码有类型提示、更严谨）。
为什么 React 不需要单独装@types/react？
这得从 “语言特性” 说起：
- ECharts 是用原生 JavaScript 写的 ——JS 是 “弱类型语言”，没有严格的类型约束；
- React 是用 TypeScript 写的 ——TS 是 “强类型语言”，自带类型定义，所以我们用 React 时不用额外装类型文件。
而 @types/echarts 就是 ECharts 的 “TS 说明书”：它给 JS 写的 ECharts 补充了类型约束，比如 “初始化 ECharts 时，参数必须是 DOM 元素”“配置项里的 type 只能是 'pie'/'bar' 等合法值”。有了它，我们用 TS 写代码时，编辑器会自动提示错误（比如传错参数类型），避免上线后踩坑。
步骤 2：写一个 “饼图组件”，让数据 “活” 起来
下面用一个 “某公司销量来源分析” 的饼图为例，写一个 React 组件：
import React, { useEffect, useRef } from 'react'
import * as echarts from 'echarts' // 导入ECharts
// 定义React函数组件
const Demo: React.FC = () => {
// 1. 用useRef获取DOM挂载点：相当于给DOM打了个“标记”
// 类型约束：只能是HTMLDivElement（div标签），初始值为null
const chartRef = useRef<HTMLDivElement>(null)
// 2. 用useEffect初始化图表：确保DOM渲染完成后再初始化
useEffect(() => {
// 先判断DOM是否存在（避免DOM还没渲染就初始化，导致报错）
if (chartRef.current) {
// 初始化ECharts实例：把DOM挂载点传给echarts.init()
const myChart = echarts.init(chartRef.current)
// 3. 配置图表参数（这是图表的“灵魂”，决定图表长什么样）
const options = {
title: {
text: '某公司财报', // 图表标题
left: 'center' // 标题居中（可选：left/right/center）
},
tooltip: {
// 鼠标 hover 时显示的提示框
trigger: 'item' // 按“单个数据项”触发提示
},
legend: {
// 图例（比如饼图旁边的“销量”标签）
orient: 'vertical', // 垂直排列
left: 'left', // 放在左边
data: ['销量'] // 图例名称，要和series里的name对应
},
series: [
// 核心数据配置：决定图表类型和数据
{
name: '销量', // 和legend的data对应
type: 'pie', // 图表类型：饼图（可选bar/line/map等）
radius: '60%', // 饼图半径（占容器的60%）
center: ['50%', '60%'], // 饼图位置（水平居中，垂直60%处）
// 具体数据：value是数值，name是标签
data: [
{ value: 335, name: '直接访问' },
{ value: 310, name: '邮件营销' },
{ value: 234, name: '联盟广告' },
{ value: 135, name: '视频广告' },
{ value: 1548, name: '搜索引擎' } // 最大的来源
],
// 可选：饼图文字样式（让标签更美观）
label: {
show: true,
fontSize: 12,
formatter: '{b}: {c} ({d}%)' // 显示“标签：数值（百分比）”
}
}
]
}
// 把配置项传给实例，渲染图表
myChart.setOption(options)
// 可选：监听窗口 resize，让图表自适应（防止窗口缩放后图表变形）
const handleResize = () => {
myChart.resize()
}
window.addEventListener('resize', handleResize)
// 组件卸载时清理：移除事件监听，销毁图表实例（避免内存泄漏）
return () => {
window.removeEventListener('resize', handleResize)
myChart.dispose()
}
}
}, []) // 空依赖数组：只在组件首次渲染时执行一次
// 4. 渲染DOM：给div设置宽高（必须！不然图表会“隐身”）
return (
<div
ref={chartRef} // 把DOM和useRef关联
style={{ width: '600px', height: '400px', margin: '0 auto' }} // 固定宽高
/>
)
}
export default Demo
把这个组件在 App 中引入：
import './App.css'
import Demo from './components/Demo.tsx'
function App() {
return (
<div className="App">
<h1 style={{ textAlign: 'center', margin: '20px 0' }}>某公司销量来源分析</h1>
<Demo />
</div>
)
}
export default App
运行项目，就能看到一个环形饼图，hover 时还会显示每个渠道的具体数值～是不是瞬间比 “纯数字” 直观多了？ 🤩
步骤 3：TypeScript 的 “类型保障”，让开发更安心
在 TS 项目中，@types/echarts 会发挥大作用：
- 写
echarts.init()时，TS 会提示 “参数必须是 HTMLDivElement 等 DOM 节点”； - 配置
option时，TS 会校验title、series等字段的类型是否正确（比如type: 'pie'不能写错成'piee'）； - 避免 “拼写错误导致图表不渲染” 的低级 bug，相当于给 ECharts 加了一层 “语法检查”～
如何让图表更 “能打”
画出基础图表只是开始，这几个小技巧能让你的图表更专业：
1. 动态更新数据
如果数据是从接口获取的，或者需要实时更新（比如实时销量），只需要修改 options.series.data，再重新调用 myChart.setOption(options) 即可：
// 假设从接口拿到新数据
const newData = [
{ value: 400, name: '直接访问' },
{ value: 350, name: '邮件营销' },
{ value: 280, name: '联盟广告' },
{ value: 150, name: '视频广告' },
{ value: 1600, name: '搜索引擎' }
]
// 更新数据并重新渲染
myChart.setOption({
series: [{
data: newData
}]
})
2. 切换图表类型
想把饼图改成柱状图？只需要改 series.type，再调整对应的配置（比如柱状图需要 x 轴和 y 轴）：
const options = {
// ...其他配置不变
xAxis: { // 柱状图需要x轴
type: 'category',
data: ['直接访问', '邮件营销', '联盟广告', '视频广告', '搜索引擎']
},
yAxis: { // 柱状图需要y轴
type: 'value'
},
series: [
{
name: '销量',
type: 'bar', // 把pie改成bar，瞬间变柱状图
data: [335, 310, 234, 135, 1548] // 数据格式也可以简化
}
]
}
3. 自定义主题
觉得默认样式不好看？可以用 ECharts 自带的主题，或者自己定义颜色：
// 1. 使用自带主题（比如'dark'主题）
const myChart = echarts.init(chartRef.current, 'dark')
// 2. 自定义颜色（比如给饼图的每个部分设置颜色）
series: [
{
// ...其他配置
color: ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FECA57'], // 自定义颜色数组
data: [/* ... */]
}
]
ECharts 支持的图表类型超级多：
- 想展示 “趋势变化”？用折线图（
type: 'line'）； - 想对比 “不同类别数据”？用柱状图（
type: 'bar'）； - 想做 “地理数据可视化”？结合地图组件（需要引入地图 JSON）；
- 甚至能做3D 图表（需要额外引入 ECharts GL）。
官网的示例库堪称 “宝藏库”，从 “基础图表” 到 “炫酷大屏”，几乎能找到所有场景的参考案例，直接复制粘贴改数据就能用，打工人效率拉满 💻～
总结：ECharts 是 “数据可视化” 的性价比之王
无论是中小项目的 “快速报表需求”，还是大型项目的 “复杂数据大屏”，ECharts 都能以 “低学习成本、高可视化效果” 的优势，帮我们把 “冰冷数字” 变成 “直观图表”。
在 React+TS 项目中，只要掌握 “init实例化 → setOption配置 → 依赖类型声明” 这几个核心步骤，就能轻松驾驭它～ ✨
