ECharts 基础接入与 Vue-ECharts 通用图表组件封装

概述

数据可视化是后台系统的高频需求，而 Apache ECharts 是国内最成熟的图表引擎之一，文档完善、图表类型齐全。在 Vue 3 项目里接入 ECharts，最稳妥的组合是 echarts + vue-echarts：echarts 提供图表引擎与渲染能力，vue-echarts 提供 Vue 包装层（响应式 option、主题注入、自动 resize、事件绑定）。本文聚焦"把这套组合封装成一个通用图表组件"，覆盖按需引入、默认开启自动缩放、option 类型选择、theme 语义与背景色分离、尺寸样式统一收口等工程要点。

学习目标

理解为什么选 echarts + vue-echarts 而非裸接 ECharts 或手写封装。
掌握 echarts/core + use() 的按需注册方式，理解渲染器和依赖组件必须手动注册。
知道 autoresize 官方默认是 false，而业务包装层通常应默认开启。
能为 option 选择 EChartsOption/ComposeOption 这类通用类型，而不是 typeof demoOption。
厘清 theme、backgroundColor、height、style 的语义边界，避免混用导致组件接口混乱。

一、为什么选 echarts + vue-echarts

单独安装 echarts 还不够，必须同时装 vue-echarts，因为后者才是 Vue 组件封装层。它的价值是把"响应式 option 驱动渲染、主题 provide/inject、自动 resize、事件绑定"这些样板逻辑包好，让你在业务页里只需传一个 option 就能出图。相比自己手写一个原生 ECharts 容器组件（见模块 11 第 3 篇），vue-echarts 省去了生命周期管理的大量细节。

选型时还要注意版本约束：当前 vue-echarts@8 依赖 ECharts 6 和 Vue 3.3+，升级时要核对 peer dependency，避免装完跑不起来。

二、echarts/core + use() 按需注册

ECharts 官方推荐的按需引入方式是：从 echarts/core 引入核心，从 echarts/charts 引入图表类型，从 echarts/components 引入坐标系/提示框/图例等组件，从 echarts/renderers 引入渲染器，最后用 use([...]) 注册。这样打包时只会包含实际用到的模块，显著减小产物体积。

import { use } from "echarts/core"
import { CanvasRenderer } from "echarts/renderers"
import { BarChart, PieChart } from "echarts/charts"
import {
  GridComponent,
  TooltipComponent,
  LegendComponent,
  TitleComponent,
} from "echarts/components"

use([CanvasRenderer, BarChart, PieChart, GridComponent, TooltipComponent, LegendComponent, TitleComponent])

两个易错点：第一，渲染器不会自动带上，至少要手动注册 CanvasRenderer 或 SVGRenderer；第二，只注册图表类型不够，很多图表还依赖对应组件（如柱状图常需要 GridComponent），漏注册会导致图表不显示或报"组件未导入"。

三、option 驱动与 autoresize 默认开启

vue-echarts 的核心入口是 option prop，传一个 EChartsOption 对象即可渲染图表。另一个关键 prop 是 autoresize，官方默认值是 false——也就是说不显式开启，页面缩放或容器宽度变化时图表不会自动适配。

在后台项目里，图表最常见的两个诉求就是"通过 option 渲染"和"容器变化时自动 resize"。因此在包装组件里把 autoresize 默认改成 true，是更符合使用习惯的工程选择（注意这是项目级增强，不是库默认值）。

Vue SFC

<script setup lang="ts">
const props = withDefaults(
  defineProps<{ option: EChartsOption; autoresize?: boolean }>(),
  { autoresize: true }
)
</script>

<template>
  <VueECharts :option="props.option" :autoresize="props.autoresize" />
</template>

四、option 的类型选择

新手常在组件里写成 typeof demoOption 来绕开类型报错，但 typeof 只会得到"当前这一个示例对象"的结构，组件类型会被示例数据绑死，不够通用。更稳妥的做法是通用封装用 EChartsOption，需要更严格类型时用 ComposeOption 显式组合允许的系列与组件类型。

import type { EChartsOption } from "echarts"

type ChartProps = {
  option: EChartsOption
}

typeof demoOption 适合示例页临时用，不适合作为通用图表组件的类型来源。类型收口到官方通用类型，才能同时保留自动提示、配置项拼写校验和系列结构约束。

五、theme 语义与背景色分离

一个常见的设计失误是把 theme 同时用来表示主题名（dark/default）和十六进制背景色（如 #00ff00）。但 vue-echarts 的 theme 对应的是 echarts.init 的主题参数：string | object，即主题名称或注册过的主题对象，不应复用来承载背景色。

正确的分工是：theme 只表达 ECharts 主题；背景色通过单独的 backgroundColor prop 或 style.backgroundColor 表达。另外，"default" 并不是 ECharts 的特殊主题名，包装层通常把它映射成 undefined：

const chartTheme = computed(() => (props.theme === "default" ? undefined : props.theme))

六、style 与 height 统一计算属性

业务里图表高度几乎不可能永远固定（卡片 300px、详情页 600px、字符串百分比都有），把高度写死是反模式。推荐把根节点样式统一收口到一个 computed 里，负责处理 height（number 自动补 px）、backgroundColor、以及用户外部传入的 style。

const normalizedHeight = computed(() =>
  typeof props.height === "number" ? `${props.height}px` : props.height
)

const rootStyle = computed<CSSProperties>(() => ({
  ...props.style,
  height: normalizedHeight.value,
  backgroundColor: props.backgroundColor ?? props.style?.backgroundColor,
}))

当 style.height 与 height prop 同时存在时，要明确优先级（通常内部 height 优先，外部 style 仅作补充），避免覆盖关系混乱。宽度默认 100% 通常合理，但高度默认值建议给明确像素（如 400px）而非 100%，除非你能确保父容器有稳定高度。

七、完整封装示例

把上述要点合到一起，一个可复用的 VChart 基础组件大致如下：