BizChart 图表容器

ECharts 声明式渲染容器：option 深度监听更新（默认全量替换，not-merge 可配）、loading / 空态统一（空对象自动判定 + empty 显式标记）、主题热切换、ResizeObserver 自适应、加载失败自动重试、chart-click 事件。dashboard 统计图、报表图表、大屏可视化卡片。

需额外安装第三方依赖

本组件依赖 echarts（可选 peer，组件库不打包）：

npm i echarts

• 组件在首次渲染时动态 import('echarts')，不使用本组件的项目零影响；
• 追求体积时不必安装完整包，可按需构建后经 echarts-lib 注入（见下方示例）；
• 未安装或加载失败时组件渲染安装指引，不会报错白屏。

基础折线图

option 声明式渲染，echarts 懒加载。

<script setup lang="ts">
/** 场景：核心指标趋势——折线图（option 声明式渲染，echarts 懒加载） */
import { BizChart } from 'vue3-ep-biz-lib'

const option = {
  tooltip: { trigger: 'axis' },
  grid: { left: 48, right: 24, top: 40, bottom: 32 },
  xAxis: { type: 'category', data: ['1月', '2月', '3月', '4月', '5月', '6月', '7月', '8月'] },
  yAxis: { type: 'value', name: '万元' },
  series: [
    {
      name: 'GMV',
      type: 'line',
      smooth: true,
      areaStyle: { opacity: 0.12 },
      data: [820, 932, 901, 1290, 1330, 1520, 1620, 1850],
    },
  ],
}
</script>

<template>
  <div style="max-width: 640px">
    <BizChart :option="option" :height="300" />
  </div>
</template>

显示代码

看板组合

柱状 + 环形双卡片，各持独立实例并独立自适应。

<script setup lang="ts">
/** 场景：看板组合——柱状 + 环形双卡片（各持独立实例，独立自适应） */
import { BizChart } from 'vue3-ep-biz-lib'

const barOption = {
  tooltip: { trigger: 'axis' },
  grid: { left: 40, right: 16, top: 30, bottom: 28 },
  xAxis: { type: 'category', data: ['华东', '华南', '华北', '西南', '东北'] },
  yAxis: { type: 'value' },
  series: [{ name: '销售额（万）', type: 'bar', barMaxWidth: 28, data: [320, 280, 254, 160, 96] }],
}

const pieOption = {
  tooltip: { trigger: 'item' },
  legend: { bottom: 0 },
  series: [
    {
      name: '渠道占比',
      type: 'pie',
      radius: ['42%', '68%'],
      center: ['50%', '44%'],
      data: [
        { value: 535, name: '线上商城' },
        { value: 310, name: '线下门店' },
        { value: 234, name: '小程序' },
        { value: 155, name: '企业直销' },
      ],
    },
  ],
}
</script>

<template>
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 14px; max-width: 860px">
    <BizChart :option="barOption" :height="260" />
    <BizChart :option="pieOption" :height="260" />
  </div>
</template>

显示代码

loading 与空态

请求期间 loading 遮罩；空 option 统一空态文案。

<script setup lang="ts">
/** 场景：loading 与空态——请求期间 loading 遮罩，无数据统一空态 */
import { onBeforeUnmount, onMounted, ref } from 'vue'
import { ElButton } from 'element-plus'
import { BizChart } from 'vue3-ep-biz-lib'

const loading = ref(false)

const baseOption = {
  tooltip: { trigger: 'axis' },
  grid: { left: 40, right: 16, top: 30, bottom: 28 },
  xAxis: { type: 'category', data: ['周一', '周二', '周三', '周四', '周五'] },
  yAxis: { type: 'value' },
  series: [{ name: '工单量', type: 'line', data: [120, 132, 101, 96, 140] }],
}

const option = ref<Record<string, unknown>>({})
let timer: number | undefined

const simulateFetch = (target: 'done' | 'empty'): void => {
  loading.value = true
  timer = window.setTimeout(() => {
    option.value = target === 'done' ? baseOption : {}
    loading.value = false
  }, 1200)
}

onMounted(() => simulateFetch('done'))
onBeforeUnmount(() => { if (timer) window.clearTimeout(timer) })
</script>

<template>
  <div style="max-width: 640px">
    <div style="margin-bottom: 10px; display: flex; gap: 8px">
      <ElButton size="small" @click="simulateFetch('done')">模拟有数据</ElButton>
      <ElButton size="small" @click="simulateFetch('empty')">模拟空数据</ElButton>
    </div>
    <BizChart :option="option" :loading="loading" :height="260" empty-text="该时间段暂无工单数据" />
  </div>
</template>

显示代码

空数据系列（empty）

empty 显式标记

series 为空数组时坐标轴仍会渲染（echarts 正常行为），传 empty 显式标记可强制统一空态；关闭开关可对比两种表现。

<script setup lang="ts">
/** 场景：空数据系列——series 空数组时坐标轴仍渲染，empty 显式标记统一走空态 */
import { ref } from 'vue'
import { ElSwitch } from 'element-plus'
import { BizChart } from 'vue3-ep-biz-lib'

/** option 带完整坐标轴但 series 数据为空（后端空列表的常见形态） */
const option = ref<Record<string, unknown>>({
  tooltip: { trigger: 'axis' },
  grid: { left: 40, right: 16, top: 30, bottom: 28 },
  xAxis: { type: 'category', data: ['周一', '周二', '周三', '周四', '周五'] },
  yAxis: { type: 'value' },
  series: [{ name: '工单量', type: 'line', data: [] }],
})

const forced = ref(true)
</script>

<template>
  <div style="max-width: 640px">
    <ElSwitch v-model="forced" active-text="empty 显式标记" style="margin-bottom: 10px" />
    <BizChart
      :option="option"
      :empty="forced"
      :height="260"
      empty-text="该时间段暂无工单数据"
    />
  </div>
</template>

显示代码

暗色主题

lightdark

theme="dark" 使用 echarts 内置主题；运行时切换 prop 即热切换（组件内部销毁重建实例，无需 :key）。

<script setup lang="ts">
/** 场景：暗色主题——theme prop 运行时热切换（组件内部销毁重建实例，无需 :key） */
import { ref } from 'vue'
import { ElRadioButton, ElRadioGroup } from 'element-plus'
import { BizChart } from 'vue3-ep-biz-lib'

const theme = ref<'light' | 'dark'>('dark')

const option = {
  tooltip: { trigger: 'axis' },
  grid: { left: 48, right: 24, top: 40, bottom: 32 },
  xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
  yAxis: { type: 'value' },
  series: [
    { name: '目标', type: 'bar', barMaxWidth: 26, data: [400, 420, 450, 500] },
    { name: '实际', type: 'bar', barMaxWidth: 26, data: [396, 441, 468, 512] },
  ],
}
</script>

<template>
  <div style="max-width: 640px">
    <ElRadioGroup v-model="theme" style="margin-bottom: 10px">
      <ElRadioButton value="light">light</ElRadioButton>
      <ElRadioButton value="dark">dark</ElRadioButton>
    </ElRadioGroup>
    <BizChart :option="option" :theme="theme === 'dark' ? 'dark' : ''" :height="280" />
  </div>
</template>

显示代码

按需注入（echartsLib）

echartsLib 注入后组件不再动态 import('echarts')，业务侧可用 echarts/core 只注册用到的图表与组件，显著压缩体积。

注入 echarts/core 按需构建产物，跳过动态 import 全量包，显著压缩业务包体积。

<script setup lang="ts">
/** 场景：按需注入——echartsLib 传入 echarts/core 按需构建产物，跳过动态 import 全量包 */
import { computed } from 'vue'
import * as echartsCore from 'echarts/core'
import { BarChart } from 'echarts/charts'
import { GridComponent, TooltipComponent } from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'
import { BizChart } from 'vue3-ep-biz-lib'
import type { BizChartLib } from 'vue3-ep-biz-lib'

echartsCore.use([BarChart, GridComponent, TooltipComponent, CanvasRenderer])

const lib = computed<BizChartLib>(() => echartsCore as unknown as BizChartLib)

const option = {
  tooltip: { trigger: 'axis' },
  grid: { left: 40, right: 16, top: 30, bottom: 28 },
  xAxis: { type: 'category', data: ['1月', '2月', '3月', '4月', '5月', '6月'] },
  yAxis: { type: 'value' },
  series: [{ name: '新增客户', type: 'bar', barMaxWidth: 24, data: [86, 102, 91, 126, 133, 168] }],
}
</script>

<template>
  <div style="max-width: 640px">
    <BizChart :option="option" :echarts-lib="lib" :height="260" />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      echartsLib 注入后组件不再动态 import('echarts')，业务侧可用 echarts/core 只注册用到的图表与组件，显著压缩体积。
    </p>
  </div>
</template>

显示代码

外部控制（expose）

点击折线上的数据点触发 chart-click；按钮切换数据集后由 expose setOption 更新（也可直接改 option）。

setOption 切换数据集 + chart-click 数据点下钻。

<script setup lang="ts">
/** 场景：外部控制——expose setOption 切换数据集 + chart-click 事件下钻 */
import { ref } from 'vue'
import { ElButton, ElTag } from 'element-plus'
import { BizChart } from 'vue3-ep-biz-lib'
import type { BizChartInstance } from 'vue3-ep-biz-lib'

const chartRef = ref<BizChartInstance>()
const clicked = ref('')

const months = ['1月', '2月', '3月', '4月', '5月', '6月']
const makeOption = (data: number[]): Record<string, unknown> => ({
  tooltip: { trigger: 'axis' },
  grid: { left: 40, right: 16, top: 30, bottom: 28 },
  xAxis: { type: 'category', data: months },
  yAxis: { type: 'value' },
  series: [{ name: '营收（万）', type: 'line', smooth: true, data }],
})

const dataset = ref<Record<string, unknown>>(makeOption([120, 132, 101, 96, 140, 168]))
const toggle = (kind: 'a' | 'b'): void => {
  dataset.value = makeOption(kind === 'a' ? [120, 132, 101, 96, 140, 168] : [88, 92, 121, 134, 150, 173])
}

const onClick = (payload: unknown): void => {
  const p = payload as { name?: string; value?: unknown }
  clicked.value = `${p.name ?? ''}：${Array.isArray(p.value) ? p.value.join(' / ') : String(p.value ?? '')}`
}
</script>

<template>
  <div style="max-width: 640px">
    <div style="margin-bottom: 10px; display: flex; gap: 8px; align-items: center">
      <ElButton size="small" @click="toggle('a')">华南大区</ElButton>
      <ElButton size="small" @click="toggle('b')">华东大区</ElButton>
      <ElTag v-if="clicked" size="small" type="warning">点击：{{ clicked }}</ElTag>
    </div>
    <BizChart
      ref="chartRef"
      :option="dataset"
      :height="260"
      @chart-click="onClick"
      @ready="() => chartRef?.setOption(dataset)"
    />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      点击折线上的数据点触发 chart-click；按钮切换数据集后由 expose setOption 更新（也可直接改 option）。
    </p>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
option	Record<string, unknown>	{}	ECharts option（深度监听更新）
echarts-lib	BizChartLib	—	注入按需构建的 echarts 库（echarts/core），跳过动态 import
theme	string	''	主题（echarts 内置 dark / light / 注册主题名），运行时切换自动重建实例
height	number	320	容器高度（px）
loading	boolean	false	加载中遮罩（自绘，与空态 / 错误态风格统一）
autoresize	boolean	true	容器尺寸变化自适应（0 尺寸触发自动跳过）
empty-text	string	'暂无数据'	空态提示文案
empty	boolean	—	显式空态标记：true 优先于空对象自动判定（如 series 空数组场景）
not-merge	boolean	true	更新时全量替换 option；含 dataZoom / legend 交互态的图表可设 false 走合并

Events

事件名	参数	说明
chart-click	(payload: unknown)	echarts click 事件透传（数据点下钻）
ready	(chart: BizChartInstanceApi)	实例初始化完成（主题切换重建后再次触发）

Expose

名称	类型	说明
getChart	() => BizChartInstanceApi | null	获取 echarts 实例
setOption	(option, opts?) => void	更新配置
resize	() => void	手动触发自适应
retry	() => void	重新解析 echarts 并渲染（加载失败后重试；option 变化时也会自动重试）

TIP

需要 mouseover、legendselectchanged 等 echarts 事件时，经 getChart() 拿到实例后用其 on() 自行绑定，组件不逐一透传。