# vue-echarts

**Repository Path**: wangankeji-fe/vue-echarts

## Basic Information

- **Project Name**: vue-echarts
- **Description**: 对  echarts 的功能封装，提供常见特性
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2020-08-10
- **Last Updated**: 2025-02-26

## Categories & Tags

**Categories**: vue-extensions

**Tags**: None

## README

# ECharts

对 [ECHARTS](https://echarts.apache.org/) 的简单封装。

此组件最大限度保留 echarts 原生用法，以降低学习成本。

## 安装

```shell script
npm i @hyjiacan/vue-echarts
```

## 用法

```vue

<template>
  <e-charts style="height: 400px;" :listen="events" :options="{}"/>
</template>
<script>
import ECharts from '@hyjiacan/vue-echarts'

export default {
  components: {ECharts},
  data() {
    return {
      events: {
        click: (e) => {
          console.info(e)
        }
      },
      mounted: false
    }
  }
}
</script>
```

> 当未明确指定高度(使用 `class` 或  `style` 指定 `width`/`height`)时，组件会自动撑满父容器。

ECharts 会监控(周期为 `500ms`，可以通过调用 [setResizeInterval](#setresizeinterval) 改变周期)组件元素的尺寸变化， 在变化后，若组件指定了 `auto-resize`
属性，那么就自动执行 `resize` 操作。

> 组件中采用了单一事件循环，不会造成大量的CPU资源占用。

## 属性

|名称|类型|必填|默认值|描述|
|---|---|---|---|---|
|options|Object|是|-|传给图片实例的配置对象|
|group|String|否|-|用于 `echarts.connect/disconnect` 的 `group` ID。参考 **echarts.connect**|
|theme|String|否|-|应用的主题。参考 **echarts.registerTheme**|
|opts|Object|否|-|附加参数。参考 **echarts.init**|
|listen|Object|否|-|需要在图表上监听的事件集合|
|auto-resize|Boolean|true|是否在容器大小变化后自动执行 resize 操作|
|empty-text|String|暂无数据|当选项为空或数据为空时的占位文本|
|show-empty-mask|Boolean|false|是否在没有数据时显示 mask 以及 `empty-text`|
|carousel|Object|-|走马灯效果(自动播放)参数，详见 [carousel](#carousel)|
|option-opts|Object|否|-|在调用 `setOption(option, opts)` 时的第二个参数|
|not-merge|Boolean|否|false|在调用 `setOption(option, notMerge, lazyUpdate)` 时的第二个参数。当指定了 `option-opts` 时无效|
|lazy-update|Boolean|否|false|在调用 `setOption(option, notMerge, lazyUpdate)` 时的第三个参数。当指定了 `option-opts` 时无效|
|delay|Number|否|0|用于延时渲染图表。一般用于存放图表的窗口具有动画时，以在动画执行完成后再进行渲染。单位为 毫秒|

在 `options` 中，添加了一些额外的属性:

- `key` 用于区分不同的数据项。一般用于对同一个图表应用不同 `options` 时，在渲染前清除原有的渲染结果。 并没有把 `key` 设置成 `prop`，是为了方便在 `option` 中直接指定，以便于同个图表展示不同的数据。

另外，可以通过 `ECharts.defaults` 设置默认值(会自动与 `setOption(option)` 中的 `option` 进行 **浅表** 合并)。

```javascript
import ECharts from '@hyjiacan/vue-echarts'

ECharts.defaults.color = ['red', 'green', 'blue']
```

`listen` 监听事件的写法:

```javascript
const handlers = {
  legendselected: function (e) {
  },
  click: {
    // 也可以是对象
    query: 'series',
    handler: function (e) {
    },
    // 指定上下文: this 指向
    context: {}
  },
}
```

### 第三方组件

目前能够自动识别并 **按需加载** 以下组件：

- [echarts-gl](https://github.com/ecomfe/echarts-gl)
- [echarts-liquidfill](https://github.com/ecomfe/echarts-liquidfill)
- [echarts-wordcloud](https://github.com/ecomfe/echarts-wordcloud)

> 需要在项目中添加对应包的依赖。

### carousel

`carousel` 是基于 [action](https://echarts.apache.org/zh/api.html#action) 的图表定时操作支持，其结构如下：

```javascript
carousel = {
  // 是否在鼠标放上时暂时，移开后恢复
  mouse: true,
  // 操作时间间隔，单位为毫秒
  interval: 5000,
  // 自动播放的动作，其值可以是对象（单个动作）或数组（多个动作）
  // 值与调用 dispatchAction 的值一致
  // 在未指定 seriesIndex 时，会自动设置为 0
  // 可以附加一个 undo 属性，用于指定此操作在下次执行时会先被取消(执行对应的取消操作)
  actions: [{
    type: 'highlight'
  }]
}
```

- 当 `carousel` 值为数组时，其表示要执行的 `actions`，同时使用默认的 `{interval: 5000, mouse: true}`
- 当 `carousel` 值为字符串时，表示其要执行的某个 `action`，同时使用默认的 `{interval: 5000, mouse: true}`

目前支持的 action:

- highlight
- legendSelect _Working in progress_
- showTip
- pieSelect
- geoSelect
- mapSelect

## 内置事件

|名称|参数|描述|
|---|---|---|
|ready|{id: String, chart: echarts}|组件首次渲染完成后触发。`id` 为 `ECharts` 组件实例的 id，并非 `echarts` 图表实例的 id|

> 仅当 `options` 不为空，并且其内的数据有效时才会渲染图表，在其后才会触发 `ready` 事件。
> `ready` 事件仅在首次渲染后会触发一次。

## 函数

### get

`ECharts.get(id)` 获取组件的 echarts 实例，`id` 为 `ready` 事件的参数， 也可以通过 `$el.getAttribute('data-echarts-id')` 获取到。

### resize

`ECharts.resize(id)` 调整指定组件的尺寸，`id` 为 `ready` 事件的参数， 也可以通过 `$el.getAttribute('data-echarts-id')` 获取到。

### resizeAll

`ECharts.resizeAll()` 调整所有组件的尺寸。

### setResizeInterval

`ECharts.setResizeInterval(timeout)` 设置自动调整尺寸的周期，单位为毫秒。默认为 `500ms`

### setInterceptor

`ECharts.setInterceptor(options)` 设置 `options` 拦截器，用于在将其提交给 echarts 前做全局处理。返回修改后的或者新的 `options` 对象。

## 插槽

|名称|参数|描述|
|---|---|---|
|prepend|-|图表前的内容，处于图表 `z-index` 的下一层|
|append|-|图表后的内容，处于图表 `z-index` 的上一层|
|empty|-|图表选项或数据为空时要显示的内容，指定此插槽时，`empty-text` 无效|

> 为了防止鼠标事件被拦截，`append` 插槽以及其子元素会忽略鼠标事件。

## 参考

- 主题和附加参数 [echarts.init](https://echarts.apache.org/zh/api.html#echarts.init)
- 绑定事件 [instance.on](https://echarts.apache.org/zh/api.html#echartsInstance.on)
- 事件类型 [events](https://echarts.apache.org/zh/api.html#events)
- [事件和行为](https://echarts.apache.org/zh/tutorial.html#ECharts%20%E4%B8%AD%E7%9A%84%E4%BA%8B%E4%BB%B6%E5%92%8C%E8%A1%8C%E4%B8%BA)
- 图表联动 [echarts.connect](https://echarts.apache.org/zh/api.html#echarts.connect)
- 主题 [echarts.registerTheme](https://echarts.apache.org/zh/api.html#echarts.registerTheme)

- [自动切换地图区域高亮](https://segmentfault.com/q/1010000018858499)

## 待办

- 仅在有图表实例时才执行定时器，如果图表被销毁，那么就停止定时器