@vue-echarts-ui/core

面向 Vue 3 的 ECharts 组件库。内置柱状图、折线图、饼图和气泡图；组件会自动管理 ECharts 实例、响应父容器尺寸变化，并在卸载时销毁实例。

安装

npm install @vue-echarts-ui/core echarts vue

vue 与 echarts 是 peer dependency，请由业务项目安装。

快速开始

从包入口导入组件，并在模板中传入 series。图例默认由 series[].name 生成；显式传入 legend 时优先级更高。

<script setup lang="ts">
import { VueBarChart } from '@vue-echarts-ui/core'

const series = [
  { name: '访问量', data: [120, 200, 150, 80] },
]
</script>

<template>
  <VueBarChart
    :series="series"
    :x-axis-data="['周一', '周二', '周三', '周四']"
    :label="{ show: true, position: 'top' }"
  />
</template>

组件

| 组件 | 用途 | 常用属性 | | --- | --- | --- | | VueBarChart | 横向或纵向柱状图 | series、xAxisData、orientation | | VueLineChart | 折线图、面积图、双 Y 轴 | series、xAxisData、area | | VuePieChart | 饼图、环形图 | series、variant | | VueBubbleChart | 三维数据的气泡图 | series、xAxisName、yAxisName | | VueBaseChart | 直接渲染完整 ECharts 配置 | option、initOptions、width、height |

预设图表组件还支持：option（覆盖默认 ECharts 配置）、legend、label、width、height 和 @click；VueBaseChart 的配置请见下文。

柱状图：横向显示

<VueBarChart
  orientation="horizontal"
  :x-axis-data="['华东', '华南', '华北']"
  :series="[{ name: '销售额', data: [320, 260, 180] }]"
/>

折线图：双 Y 轴与面积

双 Y 轴由标准 ECharts option.yAxis 和 series.yAxisIndex 配置，传入的 option 会深度覆盖组件默认项。

<VueLineChart
  :x-axis-data="['1月', '2月', '3月', '4月']"
  :area="true"
  :series="[
    { name: '订单量', data: [320, 432, 501, 634] },
    { name: '转化率', yAxisIndex: 1, data: [2.6, 3.1, 3.5, 4.2] },
  ]"
  :option="{
    yAxis: [
      { type: 'value', name: '订单量' },
      { type: 'value', name: '转化率', axisLabel: { formatter: '{value}%' } },
    ],
  }"
/>

饼图：环形图

<VuePieChart
  variant="donut"
  :series="[{
    name: '访问来源',
    data: [
      { value: 1048, name: '搜索引擎' },
      { value: 735, name: '直接访问' },
      { value: 580, name: '邮件营销' },
    ],
  }]"
  :label="{ formatter: '{b}: {d}%' }"
/>

气泡图：第三维决定气泡大小

气泡数据格式为 [x 值, y 值, 气泡量级]。未指定 series.symbolSize 时，组件会根据第三个值计算气泡直径；单个 series 的 symbolSize 可覆盖默认行为。

<script setup lang="ts">
import { VueBubbleChart } from '@vue-echarts-ui/core'

const bubbleSeries = [
  {
    name: '产品 A',
    data: [[12, 34, 80], [25, 48, 160], [38, 22, 120]],
  },
  {
    name: '产品 B',
    data: [[18, 18, 60], [32, 36, 140], [44, 52, 210]],
  },
]
</script>

<template>
  <VueBubbleChart
    :series="bubbleSeries"
    x-axis-name="客单价"
    y-axis-name="复购率"
    :label="{ show: true, formatter: '{a}' }"
  />
</template>

基础图表：使用完整 ECharts 配置

VueBaseChart 适合需要使用 ECharts 任意图表类型或高级配置的场景。传入完整的 option 后，组件会自动初始化、更新和销毁 ECharts 实例，并在容器尺寸变化时自动调用 resize。

<!-- AI Coding -->
<script setup lang="ts">
import { ref } from 'vue'
import type { EChartsCoreOption } from 'echarts'
import { VueBaseChart, type ChartClickEvent } from '@vue-echarts-ui/core'

const baseChartRef = ref<InstanceType<typeof VueBaseChart> | null>(null)
const selectedDataName = ref('')

const chartOption: EChartsCoreOption = {
  tooltip: { trigger: 'axis' },
  xAxis: { type: 'category', data: ['周一', '周二', '周三', '周四'] },
  yAxis: { type: 'value' },
  series: [{ type: 'line', data: [120, 200, 150, 80] }],
}

function handleChartClick(event: ChartClickEvent) {
  selectedDataName.value = event.name ?? ''
}

function refreshChartSize() {
  baseChartRef.value?.resizeChart()
}
</script>

<template>
  <VueBaseChart
    ref="baseChartRef"
    :option="chartOption"
    height="360px"
    :init-options="{ renderer: 'canvas' }"
    @click="handleChartClick"
  />

  <button type="button" @click="refreshChartSize">重新计算图表尺寸</button>
  <p v-if="selectedDataName">已选择：{{ selectedDataName }}</p>
</template>

| 属性 / 事件 | 说明 | 类型 / 默认值 | | --- | --- | --- | | option | 完整的 ECharts 配置，变化后自动同步到图表实例 | EChartsCoreOption，必填 | | initOptions | ECharts 初始化配置，例如指定 renderer | EChartsInitOpts，可选 | | width | 图表容器宽度 | string \| number，'100%' | | height | 图表容器高度 | string \| number，'320px' | | @click | 点击图表元素时触发 | (event: ChartClickEvent) => void |

通过组件 ref 还可以调用 resizeChart() 手动重算尺寸、disposeChart() 销毁实例，或读取 chartInstance 获取 ECharts 原生实例。

使用底层 Hook

当预设组件不满足需求时，可从 @vue-echarts-ui/core 导入 useECharts，自行构建图表。传入响应式 option 后，配置变化会自动同步到实例。

<script setup lang="ts">
import { computed, ref } from 'vue'
import type { EChartsCoreOption } from 'echarts'
import { useECharts } from '@vue-echarts-ui/core'

const chartElement = ref<HTMLElement | null>(null)
const chartOption = computed<EChartsCoreOption>(() => ({
  xAxis: { type: 'category', data: ['A', 'B', 'C'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [120, 200, 150] }],
}))

const { chartInstance, resizeChart } = useECharts({
  containerRef: chartElement,
  option: chartOption,
})
</script>

<template>
  <div ref="chartElement" style="height: 320px" />
</template>

chartInstance 可用于调用 ECharts 原生 API；resizeChart 可手动触发尺寸重算。组件卸载时会自动清理实例和 ResizeObserver。

参考：ECharts 配置项 ｜ Vue 组件基础