在 vue-vben-admin（v5版本）中，使用 ECharts 图表的方式已通过框架封装的 @vben/plugins/echarts 模块简化，结合官方示例，具体使用步骤如下：
1. 核心组件与工具导入
框架提供了封装后的 EchartsUI 组件（图表容器）和 useEcharts 钩子（图表逻辑处理），直接从插件中导入即可：
// 导入组件和钩子
import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
// 导入图表实例类型（可选，用于TypeScript类型提示）
import type { EchartsUIType } from '@vben/plugins/echarts';
2. 基础使用流程
以在页面中渲染一个折线图/柱状图/饼图为例，标准流程如下：
步骤1：创建图表容器引用
通过 ref 创建一个指向 EchartsUI 组件的引用，用于绑定图表实例：
import { ref, onMounted } from 'vue';// 创建图表容器引用
const chartRef = ref<EchartsUIType>();
步骤2：初始化图表逻辑
使用 useEcharts 钩子关联容器引用，获取渲染方法 renderEcharts：
// 初始化图表逻辑，传入容器引用
const { renderEcharts } = useEcharts(chartRef);
步骤3：定义图表配置并渲染
在 onMounted 生命周期中，通过 renderEcharts 方法传入 ECharts 配置项（option），完成图表渲染：
onMounted(() => {// 调用渲染方法，传入ECharts配置renderEcharts({// 图表配置项（与ECharts官方option一致）grid: {left: '1%',right: '1%',bottom: '3%',containLabel: true,},xAxis: {type: 'category',data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],},yAxis: {type: 'value',},series: [{data: [120, 200, 150, 80, 70, 110, 130],type: 'bar', // 图表类型（折线图用'line'，饼图用'pie'等）},],});
});
步骤4：在模板中添加图表容器
使用 EchartsUI 组件作为图表容器，并绑定之前创建的 ref：
<template><!-- 图表容器，可通过height/width属性设置尺寸 --><EchartsUI ref="chartRef" height="400px" />
</template>
3. 关键特性说明
- 自动适配主题：框架会根据全局主题（明亮/暗黑模式）自动切换 ECharts 主题，无需手动处理。
- 响应式 resize：
useEcharts内置了窗口大小监听，图表会自动适应容器尺寸变化。 - 配置项兼容：
renderEcharts接收的配置项完全兼容 ECharts 官方option格式，支持所有图表类型（折线、柱状、饼图、雷达图等）。 - 实例获取：通过
getChartInstance方法可获取原始 ECharts 实例，用于高级操作（如手动触发刷新、绑定事件等）：const { getChartInstance } = useEcharts(chartRef); // 在需要时获取实例 const instance = getChartInstance(); instance?.on('click', (params) => {console.log('图表点击事件', params); });
4. 完整示例代码
<script lang="ts" setup>
import { ref, onMounted } from 'vue';
import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
import type { EchartsUIType } from '@vben/plugins/echarts';// 图表容器引用
const chartRef = ref<EchartsUIType>();
// 初始化图表逻辑
const { renderEcharts } = useEcharts(chartRef);// 页面挂载后渲染图表
onMounted(() => {renderEcharts({title: {text: '示例图表',left: 'center',},tooltip: {trigger: 'axis',},xAxis: {type: 'category',data: ['1月', '2月', '3月', '4月', '5月', '6月'],},yAxis: {type: 'value',},series: [{name: '数据',data: [150, 230, 224, 218, 135, 147],type: 'line', // 折线图smooth: true,},],});
});
</script><template><!-- 图表容器，设置高度 --><EchartsUI ref="chartRef" height="400px" />
</template>
总结
vue-vben-admin 对 ECharts 的封装简化了初始化、主题适配和响应式处理流程，核心步骤为：
- 导入
EchartsUI和useEcharts； - 创建容器引用并关联图表逻辑；
- 定义 ECharts 配置项并通过
renderEcharts渲染； - 在模板中使用
EchartsUI作为容器。
使用时直接参考 ECharts 官方文档的配置项即可，无需关心框架底层适配细节。
