useECharts

适用于 Vue3、Nuxt3、HTML

兼容 echarts 所有 api 并且额外添加尺寸自适应容器和自动销毁等功能，echarts 能实现的它都行

使用前提

如下所示，必须先将 echarts 绑定到 globalProperties
下面代码全局引入了 echarts 也可参考 按需引入

Vue3

// main.ts
import { type App, createApp } from "vue";
import App from "./App.vue";

import * as echarts from "echarts"; 

const app = createApp(App);
// 这里$echarts写法自由，起名a、b、c都行，只要保证等号右侧引入的是echarts即可
app.config.globalProperties.$echarts = echarts; 

app.mount("#app");

Nuxt3

// plugins/config.ts
import * as echarts from "echarts";

export default defineNuxtPlugin(nuxtApp => {
  // 这里$echarts写法自由，起名a、b、c都行，只要保证等号右侧引入的是echarts即可
  nuxtApp.vueApp.config.globalProperties.$echarts = echarts;
});

最简代码

渲染echarts

<script setup lang="ts">
import { ref } from "vue";
import { useECharts } from "@pureadmin/utils";

// 初始化ECharts
const chartRef = ref();
const { setOptions } = useECharts(chartRef);

// 根据配置项渲染ECharts
setOptions({
  /** 配置项 https://echarts.apache.org/zh/option.html */
});
</script>

<template>
  <div ref="chartRef" style="width: 100%; height: 35vh" />
</template>

偏业务示例

加载动画

动态图表

接口请求和图表下钻

自定义主题

常用示例

折线图 line

柱状图 bar

饼图 pie

散点图 scatter

K 线图 candlestick

雷达图 radar

盒须图 boxplot

热力图 heatmap

关系图 graph

树图 tree

旭日图 sunburst

桑基图 sankey

漏斗图 funnel

仪表盘 gauge

象形柱图 pictorialBar

主题河流图 themeRiver

高级示例

在最右上角切换主题试试吧

demo1

demo2

demo3

demo4

demo5

demo6

API

参数

拥有两个参数，它们对echarts的 init 进行了封装，与init唯一的区别是useECharts将theme属性放到下面的options参数里并且新增一个tooltipId属性

//  在此处配置参数
const {} = useECharts(elRef, options);

参数属性	必传	说明	类型
elRef	是	获取DOM元素或组件实例引用的ref	Ref<HTMLDivElement>
options	否	拥有11个属性，具体看下面的 options 详情	EchartOptions

options 详情

参数属性	说明	类型	默认值
theme	主题色，可选default、light、dark，也可以自定义主题	Theme、Ref<Theme>、ComputedRef<Theme>	default
tooltipId	给x、y轴添加Tooltip文字提示的元素id	string	tooltipElement
devicePixelRatio	设备像素比，取自浏览器	number	window.devicePixelRatio
renderer	渲染模式，支持canvas或者svg。注意：如果是 按需引入echarts ，就要根据需求先引入CanvasRenderer或SVGRenderer，具体参考后面括号里的代码（import { CanvasRenderer, SVGRenderer } from "echarts/renderers"）	string	canvas
ssr	是否使用服务端渲染，只有在SVG渲染模式有效。开启后不再会每帧自动渲染，必须要调用 renderToSVGString 方法才能得到渲染后SVG字符串	boolean
useDirtyRect	是否开启脏矩形渲染，只有在Canvas渲染模式有效	boolean	false
useCoarsePointer	是否扩大可点击元素的响应范围。null表示对移动设备开启；true表示总是开启；false表示总是不开启	boolean
pointerSize	扩大元素响应范围的像素大小，配合opts.useCoarsePointer使用	number
width	可显式指定实例宽度，单位为像素。如果传入值为null/undefined/'auto'，则表示自动取dom（实例容器）的宽度	number、string
height	可显式指定实例高度，单位为像素。如果传入值为null/undefined/'auto'，则表示自动取dom（实例容器）的高度	number、string
locale	使用的语言，内置ZH和EN两个语言，也可以使用 echarts.registerLocale 方法注册新的语言包。目前支持的语言见 src/i18n	string

返回值、方法

返回值、方法	说明	类型
echarts	返回的echarts，功能同 echarts	ECharts
setOptions	根据配置项渲染ECharts，功能同 setOption	(options: UtilsEChartsOption, ...params: OptionsParams[]) => void
getInstance	获取通过 echarts.init 创建的实例，功能同 echartsInstance	ECharts
showLoading	显示加载动画	(params: LoadOpts) => void
hideLoading	隐藏加载动画	() => void
clear	清空当前ECharts实例，会移除实例中所有的组件和图表	() => void
resize	改变ECharts图表尺寸，使其自适应容器	() => void
getGlobalProperties	获取绑定到echarts的 globalProperties	() => EchartGlobalProperties
getDom	获取ECharts实例容器的Dom节点	() => HTMLCanvasElement
getWidth	获取ECharts实例容器的宽度	() => number
getHeight	获取ECharts实例容器的高度	() => number
getOption	获取当前ECharts实例中维护的option对象	() => EChartsCoreOption
appendData	此方法用于，在大数据量（百万以上）的渲染场景，分片加载数据和增量渲染	(opts: AppendDataOpts) => void
getDataURL	导出图表图片，返回一个base64的URL，可以设置为Image的src	(opts: DataURL) => string
getConnectedDataURL	导出联动的图表图片，返回一个base64的url，可以设置为Image的src。导出图片中每个图表的相对位置跟容器的相对位置有关	(opts: DataURL) => string
addTooltip	给x、y轴添加Tooltip文字提示。x代表x轴 y代表y轴 true(默认)代表x、y轴 （该属性生效的前提是将 xAxis 或者 yAxis 添加triggerEvent: true属性，用到哪个添加哪个）	(type: ToolTipType) => void

setOptions详解

setOptions非常重要，渲染图表都靠它。下面我们来详细了解一下吧 😜

它接收无限参数，最重要的是第一个参数，完全兼容echarts提供的 setOption 方法中所传参数，当然也完全兼容 GL配置。不仅完全兼容，我们还额外新增五个api，如下

api	说明	类型	默认
clear	是否清空当前实例，会移除实例中的图表，一般用于动态渲染	boolean	true
addTooltip	给x、y轴添加Tooltip文字提示，一般用于文字太长，x代表x轴， y代表y轴 ， true代表x、y轴（该属性生效的前提是将 xAxis 或者 yAxis 添加triggerEvent: true属性，用到哪个添加哪个）	string、boolean
delay	第一种含义（默认）：window.onresize 时改变图表尺寸的延时时间，单位毫秒，默认 300 毫秒。当 echarts 在拖拉窗口时不会自适应（一般不会出现这种情况），可以调整 delay 数值到自适应为止 第二种含义：如果设置了container，那么delay就代表指定容器元素尺寸变化的防抖时长，单位毫秒，默认40毫秒	number	300
resize	是否监听页面resize事件并在页面resize时改变图表尺寸以适应当前容器，监听及改变，true代表监听，false代表不监听	boolean	true
container	监听指定容器元素尺寸的变化，从而实现图表尺寸自适应当前容器 container可以是类名（'.class'）也可以是ID（'.id'），内部用的是document.querySelectorAll。当然它也可以是 ref 使用场景：常用于在容器宽高尺寸非固定值时，设置container实现图表尺寸自适应，毫不夸张的说，该属性支持任何情况下echarts图表自适应 注意：设置container后，resize属性就无效了。如果既想监听指定容器元素，又想监听body或更多元素，可以传字符串数组，如['.class','#id','body',...]	string、Element、string[]、Element[]

上面说完第一个参数，那么剩余参数是干嘛的呢，请看下面的 事件 解析

事件

所有 events 都在 setOptions 里配置

const { setOptions } = useECharts(elRef);

setOptions(
  {
    /** 配置项 https://echarts.apache.org/zh/option.html */
  },
  // 从第二个参数起，后面传入的剩余参数都为事件
  {
    // 点击触发
    name: "click",
    callback: params => {
      console.log("click", params);
    }
  },
  {
    // 右键触发
    name: "contextmenu",
    callback: params => {
      console.log("contextmenu", params);
    }
  },
  // 点击空白处触发
  {
    type: "zrender",
    name: "click",
    callback: params => {
      console.log("点击空白处", params);
    }
  },
  ...
);

剩余事件参数属性

属性	必传	说明	类型
name	是	事件类型名称，具体看下面的事件类型详情	ElementEventName
callback	是	回调函数，返回 params 参数	Fn
query	否	query属性，点击 此处 搜索query进行了解	string、object
type	否	echarts事件（默认）或 zrender 事件	ElementEventType

事件类型详情

下面列出常用事件类型，当然更具体的可以看 events 都支持

name	说明
click	当用户点击图表时触发
dblclick	当用户双击图表时触发
mousewheel	当用户使用鼠标滚轮时触发的事件
mouseout	当鼠标从图表上的某个数据项移开时触发
mouseover	当鼠标移动到图表上的某个数据项时触发
mouseup	当用户在图表上释放鼠标按钮时触发
mousedown	当用户在图表上按下鼠标按钮时触发
mousemove	当用户移动鼠标指针在元素上方时触发
contextmenu	当用户在图表上点击鼠标右键打开上下文菜单时触发
globalout	当鼠标从整个图表区域移出时触发
selectchanged	当图表中的数据项被选中或取消选中时触发
legendselectchanged	当图例的选中状态发生变化时触发
rendered	当图表渲染结束时触发

类型声明

import type { Ref, ComputedRef } from "vue";
import type { ECharts, EChartsOption, EChartsCoreOption } from "echarts";

interface Fn<T = any, R = T> {
  (...arg: T[]): R;
}

type ToolTipType = "x" | "y" | true;
type Theme = "default" | "light" | "dark" | string;
declare type ElementEventType = "echarts" | "zrender";
declare type ElementEventName =
  | "click"
  | "dblclick"
  | "mousewheel"
  | "mouseout"
  | "mouseover"
  | "mouseup"
  | "mousedown"
  | "mousemove"
  | "contextmenu"
  | "drag"
  | "dragstart"
  | "dragend"
  | "dragenter"
  | "dragleave"
  | "dragover"
  | "drop"
  | "globalout"
  | "selectchanged"
  | "highlight"
  | "downplay"
  | "legendselectchanged"
  | "legendselected"
  | "legendunselected"
  | "legendselectall"
  | "legendinverseselect"
  | "legendscroll"
  | "datazoom"
  | "datarangeselected"
  | "graphroam"
  | "georoam"
  | "treeroam"
  | "timelinechanged"
  | "timelineplaychanged"
  | "restore"
  | "dataviewchanged"
  | "magictypechanged"
  | "geoselectchanged"
  | "geoselected"
  | "geounselected"
  | "axisareaselected"
  | "brush"
  | "brushEnd"
  | "brushselected"
  | "globalcursortaken"
  | "rendered"
  | "finished";
interface EchartOptions {
  /** 主题色（可选`default`、`light`、`dark`，也可以 [自定义主题](https://echarts.apache.org/zh/theme-builder.html) ，默认`default`） */
  theme?: Theme | Ref<Theme> | ComputedRef<Theme>;
  /** 给`x`、`y`轴添加`Tooltip`文字提示的元素id，默认`tooltipElement` */
  tooltipId?: string;
  /** 设备像素比，默认取浏览器的值`window.devicePixelRatio` */
  devicePixelRatio?: number;
  /** 渲染模式，支持`canvas`或者`svg`，默认`canvas` */
  renderer?: "canvas" | "svg";
  /** 是否使用服务端渲染，只有在`SVG`渲染模式有效。开启后不再会每帧自动渲染，必须要调用 [renderToSVGString](https://echarts.apache.org/zh/api.html#echartsInstance.renderToSVGString) 方法才能得到渲染后`SVG`字符串 */
  ssr?: boolean;
  /** 是否开启脏矩形渲染，只有在`Canvas`渲染模式有效，默认为`false` */
  useDirtyRect?: boolean;
  /** 是否扩大可点击元素的响应范围。`null`表示对移动设备开启；`true`表示总是开启；`false`表示总是不开启 */
  useCoarsePointer?: boolean;
  /** 扩大元素响应范围的像素大小，配合`opts.useCoarsePointer`使用 */
  pointerSize?: number;
  /** 可显式指定实例宽度，单位为像素。如果传入值为`null/undefined/'auto'`，则表示自动取`dom`（实例容器）的宽度 */
  width?: number | string;
  /** 可显式指定实例高度，单位为像素。如果传入值为`null/undefined/'auto'`，则表示自动取`dom`（实例容器）的高度 */
  height?: number | string;
  /** 使用的语言，内置`ZH`和`EN`两个语言，也可以使用 [echarts.registerLocale](https://echarts.apache.org/zh/api.html#echarts.registerLocale) 方法注册新的语言包。目前支持的语言见 [src/i18n](https://github.com/apache/echarts/tree/release/src/i18n) */
  locale?: string;
}
interface OptionsParams {
  /** 事件类型名称 `必传` */
  name: ElementEventName;
  /** 回调函数，返回 [params](https://echarts.apache.org/zh/api.html#events.%E9%BC%A0%E6%A0%87%E4%BA%8B%E4%BB%B6) 参数 `必传` */
  callback: Fn;
  /** `echarts`事件（默认）或 [zrender](https://echarts.apache.org/handbook/zh/concepts/event/#%E7%9B%91%E5%90%AC%E2%80%9C%E7%A9%BA%E7%99%BD%E5%A4%84%E2%80%9D%E7%9A%84%E4%BA%8B%E4%BB%B6) 事件 */
  type?: ElementEventType;
  /** `query`属性，点击 [此处](https://echarts.apache.org/handbook/zh/concepts/event/#%E9%BC%A0%E6%A0%87%E4%BA%8B%E4%BB%B6%E7%9A%84%E5%A4%84%E7%90%86) 搜索`query`进行了解 可选 */
  query?: string | object;
}
interface LoadOpts {
  type?: string;
  opts?: {
    text?: string;
    color?: string;
    textColor?: string;
    maskColor?: string;
    zlevel?: number;
    /** 字体大小。从 `v4.8.0` 开始支持 */
    fontSize?: number;
    /** 是否显示旋转动画（spinner）。从 `v4.8.0` 开始支持 */
    showSpinner?: boolean;
    /** 旋转动画（spinner）的半径。从 `v4.8.0` 开始支持 */
    spinnerRadius?: number;
    /** 旋转动画（spinner）的线宽。从 `v4.8.0` 开始支持 */
    lineWidth?: number;
    /** 字体粗细。从 `v5.0.1` 开始支持 */
    fontWeight?: string;
    /** 字体风格。从 `v5.0.1` 开始支持 */
    fontStyle?: string;
    /** 字体系列。从 `v5.0.1` 开始支持 */
    fontFamily?: string;
  };
}
interface AppendDataOpts {
  /** 要增加数据的系列序号 */
  seriesIndex?: string | number;
  /** 增加的数据 */
  data?: Array<any>;
}
interface DataURL {
  /** 导出的格式，可选 png, jpg, svg（注意：png, jpg 只有在 canvas 渲染器的时候可使用，svg 只有在使用 svg 渲染器的时候可用） */
  type?: string;
  /** 导出的图片分辨率比例，默认为 1 */
  pixelRatio?: number;
  /** 导出的图片背景色，默认使用 option 里的 backgroundColor */
  backgroundColor?: string;
  /** 忽略组件的列表，例如要忽略 toolbox 就是 ['toolbox'] */
  excludeComponents?: Array<string>;
}
interface EventParams {
  componentIndex?: number;
  /** 当前点击的图形元素所属的组件名称，其值如 'series'、'markLine'、'markPoint'、'timeLine' 等 */
  componentType: string;
  /** 系列类型。值可能为：'line'、'bar'、'pie' 等。当 componentType 为 'series' 时有意义 */
  seriesType: string;
  /** 系列在传入的 option.series 中的 index。当 componentType 为 'series' 时有意义 */
  seriesIndex: number;
  /** 系列名称。当 componentType 为 'series' 时有意义 */
  seriesName: string;
  /** 数据名，类目名 */
  name: string;
  /** 数据在传入的 data 数组中的 index */
  dataIndex: number;
  /** 传入的原始数据项 */
  data: object;
  /** sankey、graph 等图表同时含有 nodeData 和 edgeData 两种 data，dataType 的值会是 'node' 或者 'edge'，表示当前点击在 node 还是 edge 上，其他大部分图表中只有一种 data，dataType 无意义 */
  dataType: string;
  event?: any;
  type?: string;
  targetType?: string;
  /** 传入的数据值 */
  value: string | number | Array<string | number>;
  /** 数据图形的颜色。当 componentType 为 'series' 时有意义 */
  color: string;
}
interface UtilsEChartsOption extends EChartsOption {
  /** 是否清空当前实例，会移除实例中的图表，一般用于动态渲染，默认：`true` */
  clear?: boolean;
  /** 给`x`、`y`轴添加`Tooltip`文字提示，一般用于文字太长，`x`代表`x轴`   `y`代表`y轴`   `true`代表`x、y轴`（该属性生效的前提是将 `xAxis` 或者 `yAxis` 添加`triggerEvent: true`属性，用到哪个添加哪个） */
  addTooltip?: ToolTipType;
  /** `window.onresize` 时改变图表尺寸的延时时间，单位毫秒，默认 `300` 毫秒。当 `echarts` 在拖拉窗口时不会自适应（一般不会出现这种情况），可以调整 `delay` 数值到自适应为止 */
  delay?: number;
  /** 是否监听页面`resize`事件并在页面`resize`时改变图表尺寸以适应当前容器，监听及改变，`true`(默认)代表监听 `false`代表不监听 */
  resize?: boolean;
}
interface EchartGlobalProperties {
  /** `globalProperties`属性名 */
  name?: string;
  /** `globalProperties`属性值 */
  value?: ECharts;
}