Skip to content

Latest commit

 

History

History
552 lines (430 loc) · 17.5 KB

README.zh-Hans.md

File metadata and controls

552 lines (430 loc) · 17.5 KB
Raw

Vue-ECharts

Apache ECharts 的 Vue.js 组件。

使用 Apache ECharts 5，同时支持 Vue.js 2/3。

💡 注意 💡

若您准备从 vue-echarts ≤ 5 的版本迁移到新版本，请在升级 v6 前阅读 迁移到 v6 部分文档。

没准备好的话，可以继续阅读老版本的文档。前往 →

安装 & 使用

npm & ESM

$ npm install echarts vue-echarts

要在 Vue 2 下使用 vue-echarts，需要确保 @vue/composition-api 已经安装：

npm i -D @vue/composition-api

如果你在使用基于 Vue 2 的 NuxtJS，那么还需要安装 @nuxtjs/composition-api：

npm i -D @nuxtjs/composition-api

然后在 nuxt.config.js 的 buildModules 选项中添加 '@nuxtjs/composition-api/module'。

Vue 3 
import { createApp } from 'vue'
import ECharts from 'vue-echarts'
import { use } from "echarts/core";

// 手动引入 ECharts 各模块来减小打包体积
import {
  CanvasRenderer
} from 'echarts/renderers'
import {
  BarChart
} from 'echarts/charts'
import {
  GridComponent,
  TooltipComponent
} from 'echarts/components'

use([
  CanvasRenderer,
  BarChart,
  GridComponent,
  TooltipComponent
]);

const app = createApp(...)

// 全局注册组件（也可以使用局部注册）
app.component('v-chart', ECharts)

app.mount(...)
Vue 2 
import Vue from 'vue'
import ECharts from 'vue-echarts'
import { use } from 'echarts/core'
// 手动引入 ECharts 各模块来减小打包体积

import {
  CanvasRenderer
} from 'echarts/renderers'
import {
  BarChart
} from 'echarts/charts'
import {
  GridComponent,
  TooltipComponent
} from 'echarts/components'

use([
  CanvasRenderer,
  BarChart,
  GridComponent,
  TooltipComponent
]);

// 全局注册组件（也可以使用局部注册）
Vue.component('v-chart', ECharts)

new Vue(...)

为了更小的打包体积，我们建议手动从 ECharts 引入单个图表和组件。请参考所有支持的渲染器/图表/组件。前往 →

但如果你实在需要全量引入 ECharts 从而无需手动引入模块，只需要在代码中添加：

import "echarts";

单文件组件示例

Vue 3 
<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";
import { ref, defineComponent } from "vue";

use([
  CanvasRenderer,
  PieChart,
  TitleComponent,
  TooltipComponent,
  LegendComponent
]);

export default defineComponent({
  name: "HelloWorld",
  components: {
    VChart
  },
  provide: {
    [THEME_KEY]: "dark"
  },
  setup: () => {
    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)"
            }
          }
        }
      ]
    });

    return { option };
  }
});
</script>

<style scoped>
.chart {
  height: 400px;
}
</style>
Vue 2 
<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>

CDN & 全局变量

用如下方式在 HTML 中插入 <script> 标签，并且通过 window.VueECharts 来访问组件接口：

Vue 3 
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
const app = Vue.createApp(...)

// 全局注册组件（也可以使用局部注册）
app.component('v-chart', VueECharts)

Demo →

Vue 2 
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/@vue/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
// 全局注册组件（也可以使用局部注册）
Vue.component("v-chart", VueECharts);

Demo →

可以在这里查看更多例子。

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（默认值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 方法来更新图表。

Provide / Inject

Vue-ECharts 为 theme、init-options、update-options 和 loading-options 提供了 provide/inject API，以通过上下文配置选项。例如：可以通过如下方式来使用 provide API 为 init-options 提供上下文配置：

Vue 3 
import { INIT_OPTIONS_KEY } from 'vue-echarts'
import { provide } from 'vue'

// composition API
provide(INIT_OPTIONS_KEY, ...)

// options API
{
  provide: {
    [INIT_OPTIONS_KEY]: { ... }
  }
}
Vue 2 
import { INIT_OPTIONS_KEY } from 'vue-echarts'

// in component options
{
  provide: {
    [INIT_OPTIONS_KEY]: { ... }
  }
}

方法

  • setOption →
  • getWidth →
  • getHeight →
  • getDom →
  • getOption →
  • resize →
  • dispatchAction →
  • convertToPixel →
  • convertFromPixel →
  • containPixel →
  • showLoading →
  • hideLoading →
  • getDataURL →
  • getConnectedDataURL →
  • clear →
  • dispose →

静态方法

静态方法请直接通过 echarts 本身进行调用。

事件

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 →
  • 鼠标事件
  • ZRender 事件
    • zr:click
    • zr:mousedown
    • zr:mouseup
    • zr:mousewheel
    • zr:dblclick
    • zr:contextmenu

请参考支持的事件列表。前往 →

迁移到 v6

💡 请确保同时查阅 ECharts 5 的升级指南。

vue-echarts@6 引入了如下破坏性变更：

Vue 2 支持

  • 要在 Vue 2 中使用 Vue-ECharts，现在必须安装 @vue/composition-api。

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。

本地开发

$ npm i
$ npm run serve

打开 http://localhost:8080 来查看 demo。