Vue 3 集成 ECharts 需安装 echarts 及类型定义，手动封装组件并用 ref/onMounted 初始化实例，watch 响应式配置调用 setOption（启用合并模式），监听窗口 resize 并按需引入模块以减小体积。
如果您在 Vue 3 项目中需要集成 ECharts 实现数据可视化图表，则需适配 Composition API 和响应式系统。以下是完成该集成的完整操作步骤：
一、安装 ECharts 及 Vue 封装库
Vue 3 推荐使用官方维护的 echarts 原生包配合手动封装逻辑，或选用轻量级第三方适配器以避免与 @vue/composition-api 冲突。不建议直接使用已停止维护的 vue-echarts v5 版本。
1、在项目根目录执行命令安装 ECharts 核心库：npm install echarts
2、如需 TypeScript 类型支持，额外安装类型定义：npm install --save-dev @types/echarts
立即学习“前端免费学习笔记（深入）”；
3、确认项目中未安装 vue-echarts v5 或 echarts-for-vue 等旧版封装库，避免与 Vue 3 的渲染机制冲突。
二、创建可复用的 ECharts 组件
通过 ref 获取 DOM 容器并使用 onMounted 初始化图表实例，确保图表生命周期与组件同步，防止内存泄漏和重复初始化。
1、新建文件 src/components/BaseEChart.vue
2、在组件脚本中引入 echarts 并声明响应式容器 ref：import * as echarts from 'echarts'; import { ref, onMounted, onUnmounted, watch } from 'vue';
3、定义容器 ref 和图表实例变量：const chartRef = ref(null); let chartInstance = null;
4、在 onMounted 中初始化图表：chartInstance = echarts.init(chartRef.value);
5、在 onUnmounted 中释放实例：chartInstance?.dispose();
三、绑定响应式配置与数据更新
ECharts 不自动响应 Vue 响应式对象变化，必须显式调用 setOption 触发重绘，并利用 watch 监听配置变更，避免重复 setOption 导致性能损耗。
1、声明响应式配置对象：const chartOption = ref({ tooltip: {}, xAxis: { type: 'category' }, yAxis: { type: 'value' }, series: [{ data: [1, 2, 3], type: 'bar' }] });
2、使用 watch 监听 chartOption 变化：watch(chartOption, (newOpt) => { chartInstance?.setOption(newOpt, true); }, { deep: true });
3、确保 setOption 第二个参数传入 true，启用合并模式，保留用户交互状态（如缩放、高亮）。
四、处理响应式容器尺寸变化
当父容器尺寸动态变化（如侧边栏展开/收起）时，ECharts 图表需同步 resize，否则出现渲染错位或空白区域。
1、在 onMounted 后立即调用：chartInstance?.resize();
2、监听窗口 resize 事件：window.addEventListener('resize', () => chartInstance?.resize());
3、在 onUnmounted 中移除事件监听：window.removeEventListener('resize', () => chartInstance?.resize());
五、按需引入 ECharts 模块减小包体积
全量引入 ECharts 会导致打包体积显著增大，应仅导入实际使用的图表类型与组件，例如柱状图、折线图及标题、图例等。
1、替换默认导入方式：import * as echarts from 'echarts/core';
2、按需导入必要模块：import { BarChart, LineChart } from 'echarts/charts'; import { GridComponent, TooltipComponent, LegendComponent } from 'echarts/components'; import { CanvasRenderer } from 'echarts/renderers';
3、注册模块：echarts.use([BarChart, LineChart, GridComponent, TooltipComponent, LegendComponent, CanvasRenderer]);
