封装一个通用的 ECharts 图表组件（一）

在前端开发中，数据可视化是一个非常重要的部分，ECharts 作为一个功能强大的图表库，被广泛应用于各种数据可视化场景。为了提高开发效率和代码的可维护性，封装一个通用的 ECharts 图表组件显得尤为必要。本文将介绍如何封装一个名为 QuickChart 的 Vue 组件，并探讨其内部实现细节。

一、封装动机

封装 QuickChart 组件的目的在于：

1. 减少重复代码：将 ECharts 的初始化和销毁逻辑封装在组件中，避免在多个地方重复编写相同的代码。
2. 提高可维护性：当 ECharts 升级或需求变更时，只需在组件内部进行修改，而不需要改动所有使用该组件的代码。
3. 增强灵活性：通过 props 接收图表配置，使得组件可以灵活地适应不同的图表类型和样式。

二、组件实现

2.1 HTML 结构

首先，定义组件的 HTML 结构，使用一个 div 容器来承载 ECharts 图表：

<template>
  <div class="quickChartWrapper">
    <div ref="chartRef" class="quickChart" />
  </div>
</template>

2.2 组件脚本

在 <script> 标签中，引入 ECharts 库，并导出 QuickChart 组件：

import * as echarts from 'echarts'
export default {
  name: 'QuickChart',
  props: {
    option: {
      type: Object,
      default: () => {},
    },
  },
  // ...
}

2.3 数据和方法

（1）定义组件的 data，包含图表实例和用于监听容器大小变化的 ResizeObserver：

data() {
  return {
    chart: null,
    resizeObserver: null,
  }
},

（2）实现 initChart 方法，用于初始化 ECharts 图表，并处理容器大小变化时的图表重绘：

methods: {
  initChart() {
    setTimeout(() => {
      // 检查是否已经有 ECharts 实例与当前容器关联
      let chart = echarts.getInstanceByDom(this.$refs.chartRef);
      // 如果没有实例，初始化一个新实例
      if (!chart) chart = echarts.init(this.$refs.chartRef);
      
      // 将当前的 option 配置应用到图表实例上
      chart.setOption(this.option);
      // 将实例保存在组件的 data 对象中，以便后续使用
      this.chart = chart;
      
      // 以下是模拟 tooltip 动态显示的示例代码
      // 根据配置判断是否需要执行动态显示逻辑
      if (this.option.type && this.option.type === 'move' && this.option.moveNum) {
        // 隐藏 tooltip
        this.chart.dispatchAction({ type: 'hideTip' });
        const that = this;
        let index = 0;
        const total = this.option.moveNum;
        
        // 模拟鼠标移入事件，触发 tooltip 的显示
        function showTooltip() {
          that.chart.dispatchAction({
            type: 'showTip',
            seriesIndex: 0, // 设置需要触发的系列索引
            dataIndex: index, // 设置需要触发的数据索引
          });
          // 延迟一段时间后隐藏 tooltip，并递归调用 showTooltip 函数
          setTimeout(() => {
            index++;
            if (index >= total) index = 0;
            that.chart.dispatchAction({ type: 'hideTip' }); // 隐藏 tooltip
            showTooltip();
          }, 2000);
        }
        // 开启递归调用，实现 tooltip 的自动切换展示
        showTooltip();
      }
    }, 100); // 设置延迟是为了确保图表容器已经准备好
  },
},

关键点解析

1、实例化 ECharts：首先，使用 echarts.getInstanceByDom 检查是否已经有一个 ECharts 实例与当前的图表容器关联。如果没有，使用 echarts.init 初始化一个新的实例。

2、应用配置：将通过 props 接收到的 option 配置应用到 ECharts 实例上，使用 setOption 方法。

3、保存实例引用：将初始化好的 ECharts 实例保存在组件的 data 对象中，这样在组件的其他方法中就可以方便地访问和操作这个实例。

4、响应式更新：当 option 属性变化时，通过 watch 监听来更新图表实例的配置，确保图表能够响应配置的变化。

5、模拟动态 tooltip：如果图表配置中指定了特殊的 type 和 moveNum，将模拟 tooltip 的动态显示效果。这是通过递归调用 showTooltip 函数实现的，该函数会周期性地显示和隐藏 tooltip。

6、延迟执行：使用 setTimeout 设置一个短暂的延迟，这是为了确保在调用 initChart 时，图表容器已经存在于 DOM 中，从而避免图表实例化失败。

（3）使用 watch 监听 option 属性的变化，当 option 更新时，重新设置图表的配置：

watch: {
  option: {
    handler(newVal) {
      this.chart?.clear()
      this.chart?.setOption(newVal)
    },
    deep: true,
  },
},

（4）在 mounted 和 beforeDestroy 生命周期钩子中，分别处理图表的初始化和销毁：

mounted() {
  this.initChart()
  // 容器大小发生变化，重新渲染ECharts
  this.resizeObserver = new ResizeObserver(() => {
    this.chart && this.chart.resize()
  })
  this.resizeObserver.observe(this.$refs.chartRef)
},
beforeDestroy() {
  if (this.chart) {
    this.chart.dispose()
    this.chart = null
  }
  if (this.resizeObserver) {
    this.resizeObserver.disconnect()
    this.resizeObserver.unobserve(this.$refs.chartRef)
    this.resizeObserver = null
  }
},

2.4 组件样式

最后，定义组件的样式，确保图表容器能够适应父容器的大小：

.quickChartWrapper {
  height: 100%;
  overflow: hidden;
  position: relative;
  width: 100%;
  .quickChart {
    height: 100%;
    width: 100%;
  }
}

三、技术细节

3.1 图表实例化

在 initChart 方法中，我们使用 setTimeout 来确保图表容器已经存在于 DOM 中，然后再进行实例化：

setTimeout(() => {
  let chart = echarts.getInstanceByDom(this.$refs.chartRef)
  if (!chart) chart = echarts.init(this.$refs.chartRef)
  // ...
}, 100)

3.2 响应式设计

通过 ResizeObserver 监听容器大小的变化，当容器大小变化时，自动调用 resize 方法来重新绘制图表：

this.resizeObserver = new ResizeObserver(() => {
  this.chart && this.chart.resize()
})

3.3 动态配置

组件的 option 属性允许开发者传递一个包含图表配置的对象，使得组件可以动态地展示不同的图表：

props: {
  option: {
    type: Object,
    default: () => {},
  },
},

3.4 销毁逻辑

在组件销毁前，确保释放 ECharts 图表实例和 ResizeObserver 资源，避免内存泄漏：

beforeDestroy() {
  if (this.chart) {
    this.chart.dispose()
    this.chart = null
  }
  if (this.resizeObserver) {
    this.resizeObserver.disconnect()
    this.resizeObserver.unobserve(this.$refs.chartRef)
    this.resizeObserver = null
  }
},

四、使用示例

封装后的 QuickChart 组件可以很容易地在其他 Vue 组件中使用，只需传递所需的图表配置即可：

<QuickChart :option="yourChartOption" />

五、总结

通过封装 QuickChart 组件，我们不仅提高了代码的复用性，还使得图表的使用和维护变得更加简单。同时，组件的设计也考虑了响应式和动态配置的需求，使其更加灵活和强大。希望这篇文章能够帮助到正在使用 ECharts 的开发者们，让数据可视化的开发工作变得更加轻松愉快。