在 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 官方文檔的配置項即可，無需關心框架底層適配細節。
