基于 Vue 3 封装一个 ECharts 图表组件

在前端开发中，数据可视化是展示数据的重要方式之一。ECharts 是一个强大的开源可视化库，能够帮助我们轻松地创建各种图表。本文将介绍如何在 Vue 3 项目中使用 ECharts 封装一个图表组件。

代码

<template>
  <div ref="chartRef" style="height: 100%; width: 100%"></div>
</template>

<script setup lang="ts">
import * as echarts from "echarts";
import { onMounted, onUnmounted, shallowRef, watch } from "vue";

const props = defineProps(["option"]);

// 使用 shallowRef 来创建一个对 div 元素的引用
const chartRef = shallowRef(null);

let chartInstance: echarts.ECharts | null = null;

// 初始化图表，如果图表容器不可用或图表已初始化，则不执行任何操作。
const initChart = () => {
  if (!chartRef.value) {
    console.error("图表容器不可用。");
    return;
  }
  if (chartInstance) {
    // 防止重复初始化
    return;
  }
  try {
    chartInstance = echarts.init(chartRef.value);
    chartInstance.setOption(props.option);
  } catch (error) {
    console.error("无法加载图表：", error);
  }
};

// 当组件挂载时调用的函数，用于初始化图表并添加窗口大小调整的监听器
onMounted(() => {
  initChart();
  const handleResize = () => {
    if (chartInstance) {
      chartInstance.resize();
    }
  };
  // 监听窗口大小改变，并重新调整图表大小
  window.addEventListener("resize", handleResize);

  // 当组件卸载时调用的函数，用于清理资源
  onUnmounted(() => {
    if (chartInstance) {
      chartInstance.dispose();
      chartInstance = null;
    }
    window.removeEventListener("resize", handleResize);
  });
});

// 监听 props.option 的变化，以更新图表选项
watch(
  () => props.option,
  (newOption: echarts.EChartsOption) => {
    if (chartInstance) {
      chartInstance.setOption(newOption);
      chartInstance.resize();
    }
  }
);
</script>

说明

容器定义

<template>
  <div ref="chartRef" style="height: 100%; width: 100%"></div>
</template>

这段代码用于创建图表容器，并使用 ref 指令获取该元素的引用。相比于使用 id，ref 更加灵活，避免了 id 重复的问题，且更符合 Vue 的响应式编程风格。

引用实例

const chartRef = shallowRef(null);
let chartInstance: echarts.ECharts | null = null;

使用 shallowRef 创建对 div 元素的引用。shallowRef 和 ref 的区别在于，shallowRef 仅对引用对象的第一层做响应式处理，避免了不必要的性能消耗。本文引用的 DOM 元素不需要深层次的响应式处理，所以选择 shallowRef。

初始化

const initChart = () => {
  if (!chartRef.value) {
    console.error("图表容器不可用。");
    return;
  }
  if (chartInstance) {
    // 防止重复初始化
    return;
  }
  try {
    chartInstance = echarts.init(chartRef.value);
    chartInstance.setOption(props.option);
  } catch (error) {
    console.error("无法加载图表：", error);
  }
};

通过 echarts.init 初始化图表实例，并设置图表配置。该函数首先检查 chartRef 是否存在，以避免在容器不可用时初始化图表。然后，通过 echarts.init 初始化图表实例，并设置图表配置。

挂载卸载

onMounted(() => {
  initChart();
  const handleResize = () => {
    if (chartInstance) {
      chartInstance.resize();
    }
  };
  // 监听窗口大小改变，并重新调整图表大小
  window.addEventListener("resize", handleResize);

  // 当组件卸载时调用的函数，用于清理资源
  onUnmounted(() => {
    if (chartInstance) {
      chartInstance.dispose();
      chartInstance = null;
    }
    window.removeEventListener("resize", handleResize);
  });
});

挂载不必解释，卸载是为了及时清理，防止可能的内存泄露问题。

及时更新

watch(
  () => props.option,
  (newOption: echarts.EChartsOption) => {
    if (chartInstance) {
      chartInstance.setOption(newOption);
      chartInstance.resize();
    }
  }
);