说明

随着 echarts 版本的更迭，很多书写方式都有了变化，本文于2021/04/25更新了一次，具体可查看源码：github 源码地址

为什么需要封装 echarts

• 每个开发者在制作图表时都需要从头到尾书写一遍完整的 option 配置，十分冗余
• 在同一个项目中，各类图表设计十分相似，甚至是相同，没必要一直做重复工作
• 可能有一些开发者忘记考虑 echarts 更新数据的特性，以及窗口缩放时的适应问题。这样导致数据更新了 echarts 视图却没有更新，窗口缩放引起 echarts 图形变形问题

我希望这个 echarts 组件能设计成什么样

• 业务数据和样式配置数据分离，我只需要传入业务数据就行了
• 它的大小要完全由使用者决定
• 不会因为缩放出现变形问题，而是能很好地自适应
• 有时候某个图表的样式可能有点不一样，希望能保留自己配置样式的灵活性
• 无论传入什么数据都能正确地更新视图
• 如果我传入的数据为空，能展示一个空状态

公共组件结构建议

• 当你把它书写为一个公共组件时，我我希望它应该是这样：将单独机械的配置表独立成一份文件，暴露一个必要的 vue 单文件，同时携带一份 README 说明文档，当然，文档里面需要有关于你写的组件的使用示例和入参含义说明，这在大型项目中非常重要。

vue 单文件代码

• echart_pie 完整代码如下：

<template>
  <div class="chart"></div>
</template>
<script>
import { merge } from "lodash";
import * as echarts from "echarts";
import { BASIC_OPTION } from "./default_option";
import { COLOR_ARRAY } from "../color";
import ResizeListener from "element-resize-detector";
export default {
  name: "ChartPie",
  props: {
    // 正常的业务数据，对应 echarts 饼图配置中 series[0].data
    seriesData: {
      type: Array,
      required: true,
      default: () => [],
    },
    // 表示需要特殊定制的配置
    // 一般 UI 会规定一个统一的设计规范（比如颜色，字体，图例格式，位置等）
    // 但不排除某个图标会和设计规范不同，需要特殊定制样式，所以开放这个配置，增强灵活性
    extraOption: {
      type: Object,
      default: () => ({}),
    },
  },
  data() {
    return {
      chart: null,
    };
  },
  watch: {
    seriesData: {
      deep: true,
      handler() {
        this.updateChartView();
      },
    },
  },
  mounted() {
    this.chart = echarts.init(this.$el);
    this.updateChartView();
    window.addEventListener("resize", this.handleWindowResize);
    this.addChartResizeListener();
  },
  beforeDestroy() {
    window.removeEventListener("resize", this.handleWindowResize);
  },
  methods: {
    /**
      将业务数据加入到基础样式配置中
      @returns {Object} 完整的 echart 配置
     */
    assembleDataToOption() {
      // 这部分的图例 formatter 取决于 UI 要求，如果你的项目中不需要，就可以不写 formatter
      // 由于 echarts 版本的迭代，这里的写法也有稍许改变
      const formatter = (name) => {
        const total = this.seriesData.reduce((acc, cur) => acc + cur.value, 0);
        const data = this.seriesData.find((item) => item.name === name) || {};
        const percent = data.value
          ? <span class="hljs-subst">${<span class="hljs-built_in">Math</span>.round((data.value&nbsp;/&nbsp;total)&nbsp;*&nbsp;<span class="hljs-number">100</span>)}</span>%
          : "0%";
        return <span class="hljs-subst">${name}</span>&nbsp;<span class="hljs-subst">${percent}</span>;
      };
      return merge(
        {},
        BASIC_OPTION,
        { color: COLOR_ARRAY },
        {
          legend: { formatter },
          series: [{ data: this.seriesData }],
        },
        this.extraOption
      );
    },
    /**
      对 chart 元素尺寸进行监听，当发生变化时同步更新 echart 视图
     /
    addChartResizeListener() {
      const instance = ResizeListener({
        strategy: "scroll",
        callOnAdd: true,
      });
      instance.listenTo(this.$el, () => {
        if (!this.chart) return;
        this.chart.resize();
      });
    },
    /**
      更新 echart 视图
     /
    updateChartView() {
      if (!this.chart) return;
      const fullOption = this.assembleDataToOption();
      this.chart.setOption(fullOption, true);
    },
    /**
      当窗口缩放时，echart 动态调整自身大小
     /
    handleWindowResize() {
      if (!this.chart) return;
      this.chart.resize();
    },
  },
};
</script>
<style lang="less" scoped>
.chart {
  width: 100%;
  height: 100%;
}
</style>

• index 完整代码如下：

<template>
  <Empty v-if="isSeriesEmpty" description="暂无数据" />
  <chart-pie v-else v-bind="$props" />
</template>
<script>
import { isEmpty } from "lodash";
import ChartPie from "./echart_pie.vue";
import { Empty } from "vant";
export default {
  name: "EchartPie",
  components: { ChartPie, Empty },
  props: ChartPie.props,
  computed: {
    // 针对饼图数据是不是无效的判断
    isSeriesEmpty() {
      return (
        isEmpty(this.seriesData) || this.seriesData.every((item) => !item.value)
      );
    },
  },
};
</script>

关于源码的说明

• 在源码中，我用到了 lodash 的一个公共函数merge, 它表示递归合并来源对象自身和继承的可枚举属性到目标对象。后续的来源对象属性会覆盖之前同名的属性
• 另外一个有幸被我宠幸的函数是isEmpty，当我传入的业务数据为空时，比如空数组[]、undefined、null时，都会被认为这是一个无数据的情况，这时候我们就展示一个空状态的组件，它可能由一张背景图构成；
• 在绑定到具体的 DOM 元素时，我没有用querySelector选择器去选择一个类或者是用Math.random生成的 id，因为这两者都不是绝对可靠的，我直接使用当前 vue 示例关联的根 DOM 元素$el
• 我监听窗口大小的变化，并为这种情况添加对应的事件处理函数 --echarts 自带的resize方法，使 echarts 图形不会变形
• 将对应 DOM 的宽高设为 100%，让其大小完全由使用者提供的容器控制
• setOption方法的第二个参数表示传入的新 option 是否不与之前的旧 option 进行合并，默认居然是 false，即合并。这显然不行，我们需要每次的业务配置都是完全独立的
• 命名非常语义化，一看就懂
• 保留了自己需要单独配置一些定制样式的灵活性，即 extraOption

default_option.js 应该包括哪些内容

• 正常情况下暴露一个基础配置BASIC_OPTION就可以了

element-resize-detector 是干啥的？

这是一个用于监听 DOM 元素尺寸变化的插件。我们已经对窗口缩放做了监听，但是有时候其父级容器的大小也会动态改变的。

我们对父级容器的宽度进行监听，当父级容器的尺寸发生变化时，echart 能调用自身的 resize 方法，保持视图正常。

当然，这个不适用于 tab 选项卡的情况，在 tab 选项卡中，父级容器从display:none到有实际的 clientWidth，可能会比注册一个 resizeDetector 先完成，所以等开始监听父级容器 resize 的时候，可能为时已晚。

在 tab 选项卡中很容易出现这种场景：

看起来非常的逗，只有一点点大。解决这个问题，最有效的方法还是在切换选项卡时手动去通过 ref 获取 echart 实例，并手动调用 resize 方法，这是最安全的，也是最有效的。

组件使用示例

<template>
  <div class="echart-pie-wrap">
    <echart-pie :series-data="dataList" :extra-option="extraOption" />
  </div>
</template>
<script>
import EchartPie from "@/components/echart_pie";
export default {
  components: {
    EchartPie,
  },
  data() {
    return {
      dataList: [
        {
          name: "西瓜",
          value: 20,
        },
        {
          name: "橘子",
          value: 13,
        },
        {
          name: "杨桃",
          value: 33,
        },
      ],
      extraOption: {
        color: ["#fe883a", "#2d90d1", "#f75981", "#90e2a9"],
      },
    };
  },
};
</script>
<style lang="less">
.echart-pie-wrap {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 90vw;
  height: 90vh;
  margin: 20px auto;
}
</style>

效果图

• 当数据正常时，效果如下

image.png

• 当无数据时，效果如下

image.png

关于灵活性

这里面提供的封装只是一种大概的思路，实际项目中，可能会与这里出现偏差。软件开发没有银弹可言，非常适合我这个项目的，可能在细节上不太适合看这篇文章的你。但是思路是类似的，可以对照着做一些调整。