Vue-ECharts
Apache ECharts™ (v5) 的 Vue.js (v2/v3) 组件。
!IMPORTANT 我们新发布了一个导入代码生成器,只需要把option
代码粘贴进去,就可以得到精确的导入代码。
试一试 →
💡 注意 💡
若您准备从vue-echarts
≤ 5 的版本迁移到新版本,请在升级 v6 前阅读 迁移到 v6 部分文档。没准备好的话,可以继续阅读老版本的文档。前往 →
安装 & 使用
npm & ESM
npm i echarts vue-echarts
要在 Vue 2(<2.7.0)下使用
vue-echarts
,需要确保 @vue/composition-api
已经安装(TypeScript 支持还需要 @vue/runtime-core
):npm i @vue/composition-api
npm i @vue/runtime-core # TypeScript 支持
如果你在使用基于 Vue 2 的 NuxtJS,则需要安装
@nuxtjs/composition-api
:npm i @nuxtjs/composition-api
然后在
nuxt.config.js
的 buildModules
选项中添加 '@nuxtjs/composition-api/module'
。示例
Vue 3 Demo →<template>
<v-chart class="chart" :option="option" />
</template>
<script setup>
import { use } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import { PieChart } from "echarts/charts";
import {
TitleComponent,
TooltipComponent,
LegendComponent
} from "echarts/components";
import VChart, { THEME_KEY } from "vue-echarts";
import { ref, provide } from "vue";
use([
CanvasRenderer,
PieChart,
TitleComponent,
TooltipComponent,
LegendComponent
]);
provide(THEME_KEY, "dark");
const option = ref({
title: {
text: "Traffic Sources",
left: "center"
},
tooltip: {
trigger: "item",
formatter: "{a} <br/>{b} : {c} ({d}%)"
},
legend: {
orient: "vertical",
left: "left",
data: ["Direct", "Email", "Ad Networks", "Video Ads", "Search Engines"]
},
series: [
{
name: "Traffic Sources",
type: "pie",
radius: "55%",
center: ["50%", "60%"],
data: [
{ value: 335, name: "Direct" },
{ value: 310, name: "Email" },
{ value: 234, name: "Ad Networks" },
{ value: 135, name: "Video Ads" },
{ value: 1548, name: "Search Engines" }
],
emphasis: {
itemStyle: {
shadowBlur: 10,
shadowOffsetX: 0,
shadowColor: "rgba(0, 0, 0, 0.5)"
}
}
}
]
});
</script>
<style scoped>
.chart {
height: 400px;
}
</style>
Vue 2 Demo →
<template>
<v-chart class="chart" :option="option" />
</template>
<script>
import { use } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import { PieChart } from "echarts/charts";
import {
TitleComponent,
TooltipComponent,
LegendComponent
} from "echarts/components";
import VChart, { THEME_KEY } from "vue-echarts";
use([
CanvasRenderer,
PieChart,
TitleComponent,
TooltipComponent,
LegendComponent
]);
export default {
name: "HelloWorld",
components: {
VChart
},
provide: {
[THEME_KEY]: "dark"
},
data() {
return {
option: {
title: {
text: "Traffic Sources",
left: "center"
},
tooltip: {
trigger: "item",
formatter: "{a} <br/>{b} : {c} ({d}%)"
},
legend: {
orient: "vertical",
left: "left",
data: [
"Direct",
"Email",
"Ad Networks",
"Video Ads",
"Search Engines"
]
},
series: [
{
name: "Traffic Sources",
type: "pie",
radius: "55%",
center: ["50%", "60%"],
data: [
{ value: 335, name: "Direct" },
{ value: 310, name: "Email" },
{ value: 234, name: "Ad Networks" },
{ value: 135, name: "Video Ads" },
{ value: 1548, name: "Search Engines" }
],
emphasis: {
itemStyle: {
shadowBlur: 10,
shadowOffsetX: 0,
shadowColor: "rgba(0, 0, 0, 0.5)"
}
}
}
]
}
};
}
};
</script>
<style scoped>
.chart {
height: 400px;
}
</style>
!IMPORTANT 我们鼓励手动从 ECharts 中引入组件和图表,以减小打包体积。我们已经为此构建了一个导入代码生成器。你只需要把option
代码粘贴进去,就可以得到精确的导入代码。
试一试 →
但如果你实在需要全量引入 ECharts 从而无需手动引入模块,只需要在代码中添加:
import "echarts";
CDN & 全局变量
用如下方式在 HTML 中插入<script>
标签,并且通过 window.VueECharts
来访问组件接口:Vue 3 Demo →
<script src="https://cdn.jsdelivr.net/npm/vue@3.4.23"></script>
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.7.1"></script>
const app = Vue.createApp(...)
// 全局注册组件(也可以使用局部注册)
app.component('v-chart', VueECharts)
Vue 2 Demo →
<script src="https://cdn.jsdelivr.net/npm/vue@2.7.16"></script>
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.7.1"></script>
// 全局注册组件(也可以使用局部注册)
Vue.component("v-chart", VueECharts);
可以在这里查看更多例子。
Prop
init-options: object
初始化附加参数。请参考
echarts.init
的 opts
参数。前往 →Inject 键名:
INIT_OPTIONS_KEY
。theme: string | object
要应用的主题。请参考
echarts.init
的 theme
参数。前往 →Inject 键名:
THEME_KEY
。option: object
ECharts 的万能接口。修改这个 prop 会触发 ECharts 实例的
setOption
方法。查看详情 →> 💡 在没有指定
update-options
时,如果直接修改 option
对象而引用保持不变,setOption
方法调用时将默认指定 notMerge: false
;否则,如果为 option
绑定一个新的引用,将指定 notMerge: true
。update-options: object
图表更新的配置项。请参考
echartsInstance.setOption
的 opts
参数。前往 →Inject 键名:
UPDATE_OPTIONS_KEY
。group: string
图表的分组,用于联动。请参考
echartsInstance.group
。前往 →autoresize: boolean | { throttle?: number, onResize?: () => void }
(默认值false
)
图表在组件根元素尺寸变化时是否需要自动进行重绘。也可以传入一个选项对象来指定自定义的节流延迟和尺寸变化时的额外回调函数。
loading: boolean
(默认值:false
)
图表是否处于加载状态。
loading-options: object
加载动画配置项。请参考
echartsInstance.showLoading
的 opts
参数。前往 →Inject 键名:
LOADING_OPTIONS_KEY
。manual-update: boolean
(默认值false
)
在性能敏感(数据量很大)的场景下,我们最好对于
option
prop 绕过 Vue 的响应式系统。当将 manual-update
prop 指定为 true
且不传入 option
prop 时,数据将不会被监听。然后,需要用 ref
获取组件实例以后手动调用 setOption
方法来更新图表。事件
可以使用 Vue 的v-on
指令绑定事件。<template>
<v-chart :option="option" @highlight="handleHighlight" />
</template>
Note
仅支持.once
修饰符,因为其它修饰符都与 DOM 事件机制强耦合。
Vue-ECharts 支持如下事件:
highlight
→downplay
→selectchanged
→legendselectchanged
→legendselected
→legendunselected
→legendselectall
→legendinverseselect
→legendscroll
→datazoom
→datarangeselected
→timelinechanged
→timelineplaychanged
→restore
→dataviewchanged
→magictypechanged
→geoselectchanged
→geoselected
→geounselected
→axisareaselected
→brush
→brushEnd
→brushselected
→globalcursortaken
→rendered
→finished
→- 鼠标事件
click
→
- dblclick
→
- mouseover
→
- mouseout
→
- mousemove
→
- mousedown
→
- mouseup
→
- globalout
→
- contextmenu
→- ZRender 事件
zr:click
- zr:mousedown
- zr:mouseup
- zr:mousewheel
- zr:dblclick
- zr:contextmenu
请参考支持的事件列表。前往 →
原生 DOM 事件
由于 Vue-ECharts 默认将事件绑定到 ECharts 实例,因此在使用原生 DOM 事件时需要做一些特殊处理。你需要在事件名称前加上native:
前缀来绑定原生 DOM 事件(可以在 Vue 2 中也可以使用 .native
修饰符,但这在 Vue 3 中已被废弃)。<template>
<v-chart @native:click="handleClick" />
</template>
Provide / Inject
Vue-ECharts 为theme
、init-options
、update-options
和 loading-options
提供了 provide/inject API,以通过上下文配置选项。例如:可以通过如下方式来使用 provide API 为 init-options
提供上下文配置:Vue 3
import { THEME_KEY } from 'vue-echarts'
import { provide } from 'vue'
// 组合式 API
provide(THEME_KEY, 'dark')
// 选项式 API
{
provide: {
[THEME_KEY]: 'dark'
}
}
Vue 2
import { THEME_KEY } from 'vue-echarts'
// 组件选项中
{
provide: {
[THEME_KEY]: 'dark'
}
}
Note
在 Vue 2 中,如果你想动态地改变这些选项,那么你需要提供一个对象。// 组件选项中 { data () { return { theme: { value: 'dark' } } }, provide () { return { [THEME_KEY]: this.theme } } }
方法
setOption
→getWidth
→getHeight
→getDom
→getOption
→resize
→dispatchAction
→convertToPixel
→convertFromPixel
→containPixel
→showLoading
→hideLoading
→getDataURL
→getConnectedDataURL
→clear
→dispose
→
静态方法
静态方法请直接通过echarts
本身进行调用。CSP: style-src
或 style-src-elem
如果你正在应用 CSP 来防止内联 <style>
注入,则需要使用 dist/csp
目录中的文件,并手动引入 dist/csp/style.css
。迁移到 v6
💡 请确保同时查阅 ECharts 5 的升级指南。
vue-echarts@6
引入了如下破坏性变更:Vue 2 支持
- 要在
vue@2.7.0
之前的版本中使用 Vue-ECharts,必须安装@vue/composition-api
(还需要安装@vue/runtime-core
来支持 TypeScript)。
Prop
options
重命名为option
,以和 ECharts 本身保持一致。- 更新
option
将采用update-options
中的配置,不再检查是否发生引用变化。 watch-shallow
被移除。在性能关键场景请使用manual-update
。
方法
mergeOptions
重命名为setOption
,以和 ECharts 本身保持一致。showLoading
与hideLoading
被移除。请使用loading
与loading-options
prop。appendData
被移除。(由于 ECharts 5 引入的破坏性变更。)- 所有静态方法被从
vue-echarts
移除。可以直接使用echarts
本身的这些方法。
计算 Getter
- 计算 getter(
width
、height
、isDisposed
和computedOptions
)被移除。请分别使用getWidth
、getHeight
、isDisposed
和getOption
方法代替。
样式
- 现在组件根元素尺寸默认为
100%×100%
,而非原来的600×400
。
本地开发
pnpm i
pnpm serve
打开
http://localhost:8080
来查看 demo。