Merge pull request #18 from ambit-tsai/dev

feat: deep watch prop "option"
ambit-tsai · May 4, 2021 · 5bb9c06 · 5bb9c06
2 parents 5a48637 + 794d48c
commit 5bb9c06
Show file tree

Hide file tree

Showing 14 changed files with 393 additions and 1,742 deletions.
diff --git a/README.md b/README.md
@@ -2,15 +2,15 @@
 
 
 # ECharts For Vue&nbsp;&nbsp;![Version](https://img.shields.io/npm/v/echarts-for-vue.svg)
-📊📈 ECharts wrapper component for Vue 3 and 2
+📊📈 ECharts wrapper component for Vue 3, 2 and TypeScript
 
 
 ## Features
 1. Support for Vue 3 and 2;
+1. Support auto resize;
 1. Conform to the habits of Vue and ECharts users;
 1. Provide pure function API, no side effects;
 1. Lightweight encapsulation, easy to use;
-1. Support auto resize;
 
 
 ## Install
@@ -23,8 +23,8 @@ npm i -S echarts-for-vue
 1. Vue 3
 ```javascript
 import { createApp, h } from 'vue';
-import * as echarts from 'echarts';
 import { plugin } from 'echarts-for-vue';
+import * as echarts from 'echarts';
 
 const app = createApp({ /*...*/ });
 app.use(plugin, { echarts, h });                        // use as a plugin
@@ -35,19 +35,17 @@ app.use(plugin, { echarts, h });                        // use as a plugin
 </template>
 
 <script>
+    import { createComponent } from 'echarts-for-vue';
     import * as echarts from 'echarts';
     import { h } from 'vue';
-    import { createComponent } from 'echarts-for-vue';
 
     export default {
         components: {
             ECharts: createComponent({ echarts, h }),   // use as a component
         },
-        data() {
-            return {
-                option: { /*...*/ },
-            };
-        },
+        data: () => ({
+            option: { /*...*/ },
+        }),
         methods: {
             doSomething() {
                 this.$refs.chart.inst.getWidth();       // call the method of ECharts instance
@@ -60,8 +58,8 @@ app.use(plugin, { echarts, h });                        // use as a plugin
 2. Vue 2
 ```javascript
 import Vue from 'vue';
-import * as echarts from 'echarts';
 import { plugin } from 'echarts-for-vue';
+import * as echarts from 'echarts';
 
 Vue.use(plugin, { echarts });                           // use as a plugin
 ```
@@ -71,18 +69,16 @@ Vue.use(plugin, { echarts });                           // use as a plugin
 </template>
 
 <script>
-    import * as echarts from 'echarts';
     import { createComponent } from 'echarts-for-vue';
+    import * as echarts from 'echarts';
 
     export default {
         components: {
             ECharts: createComponent({ echarts }),      // use as a component
         },
-        data() {
-            return {
-                option: { /*...*/ },
-            };
-        },
+        data: () => ({
+            option: { /*...*/ },
+        }),
         methods: {
             doSomething() {
                 this.$refs.chart.inst.getWidth();       // call the method of ECharts instance
@@ -98,23 +94,24 @@ Vue.use(plugin, { echarts });                           // use as a plugin
 ## Global API
 |Definition|Return|Description|
 |-|-|-|
-|`createComponent`(*initialOptions*: object): object|Component definition object|Create a component|
-|`plugin`(*app*: Vue, *initialOptions*: object): void||The installation method of plugin|
+|`createComponent`(*options*: Options): object|Component definition object|Create a component|
+|`plugin`(*app*: Vue, *options*: Options): void||The installation method of plugin|
 
 
-## initialOptions
+## Options
 |Property|Type|Default|Optional|Description|
 |-|-|-|-|-|
-|echarts|object|||The global object of ECharts library|
-|h|function||✔|The method `createElement` of Vue (**Required** for Vue 3)|
-|ResizeObserver|function|window.ResizeObserver|✔|When the global `ResizeObserver` doesn't exist, the <a href="https://github.com/que-etc/resize-observer-polyfill" target="_blank">polyfill</a> provides support|
+|echarts|typeof echarts|||The global object of ECharts library|
+|h|Function||✔|The method `createElement` of Vue (**Required** for Vue 3)|
+|ResizeObserver|typeof ResizeObserver|window.ResizeObserver|✔|When the global `ResizeObserver` doesn't exist, the <a href="https://github.com/que-etc/resize-observer-polyfill" target="_blank">polyfill</a> provides support|
 |name|string|"ECharts"|✔|The registered name of the component|
+|deepWatchOption|boolean|true|✔|deep watch prop "option"|
 
 
 ## Instance Properties
 |Name|Type|ReadOnly|Description|
 |-|-|-|-|
-|inst|object|✔|ECharts instance|
+|inst|ECharts|✔|ECharts instance|
 
 
 ## props
@@ -124,25 +121,32 @@ Vue.use(plugin, { echarts });                           // use as a plugin
 |initOpts|object|||The parameter `opts` of `echarts.init` method, <a href="https://echarts.apache.org/en/api.html#echarts.init" target="_blank">see</a>|
 |loading|boolean|false|✔|Shows loading animation|
 |loadingType|string|"default"||The parameter `type` of ECharts instance method `showLoading`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.showLoading" target="_blank">see</a>|
-|loadingOpts|object|||The parameter `opts` of ECharts instance method `showLoading`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.showLoading" target="_blank">see</a>|
-|option|object||✔|The parameter `option` of ECharts instance method `setOption`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.setOption" target="_blank">see</a>|
-|setOptionOpts|object|||The parameter `opts` of ECharts instance method `setOption`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.setOption" target="_blank">see</a>|
+|loadingOpts|EChartsLoadingOption|||The parameter `opts` of ECharts instance method `showLoading`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.showLoading" target="_blank">see</a>|
+|option|EChartOption||✔|The parameter `option` of ECharts instance method `setOption`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.setOption" target="_blank">see</a>|
+|optionOpts|EChartsOptionConfig|||The parameter `opts` of ECharts instance method `setOption`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.setOption" target="_blank">see</a>|
 |events|Arguments[]|||An array element is the arguments of ECharts instance method `on`, <a href="https://echarts.apache.org/en/api.html#echartsInstance.on" target="_blank">see</a>|
-|autoResize|boolean|true|✔|Auto resize (Based on `ResizeObserver`, forward compatibility via <a href="https://github.com/que-etc/resize-observer-polyfill" target="_blank">polyfill</a>)|
+|autoResize|boolean|true|✔|Auto resize|
 
 ***Beyond the `props` above, the remaining properties are passed to the root element of the component, such as `style`, `class` or `onclick`***
 
 
+## Events
+|Name|Description|
+|-|-|
+|resize|Trigger when chart is resized|
+
+
 ## methods
 |Definition|Description|
 |-|-|
-|`setOption`(*option*: object, *opts*: object): void|Call the method `setOption` of ECharts instance, <a href="https://echarts.apache.org/en/api.html#echartsInstance.setOption" target="_blank">see</a>|
+|`setOption`(*option*: EChartOption, *opts*?: EChartsOptionConfig): void|Call the method `setOption` of ECharts instance, <a href="https://echarts.apache.org/en/api.html#echartsInstance.setOption" target="_blank">see</a>|
 |`resize`(): void|Resize chart (Based on the size of root element)|
 |`addResizeListener`(): void|Add "resize" listener|
 |`removeResizeListener`(): void|Remove "resize" listener|
 
 
 ## Contact
-1. *WeChat*: ambit_tsai
+1. *WeChat*: cai_fanwei
+1. *QQ*: 854521460
 1. *QQ Group*: 663286147
 1. *E-mail*: ambit_tsai@qq.com
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -2,15 +2,15 @@
 
 
 # ECharts For Vue&nbsp;&nbsp;![Version](https://img.shields.io/npm/v/echarts-for-vue.svg)
-📊📈 适用于 Vue 3 和 2 的 ECharts 包装组件
+📊📈 适用于 Vue 3、2 和 TypeScript 的 ECharts 包装组件
 
 
 ## 特点
 1. 支持 Vue 3 和 2；
+1. 支持图表大小自适应；
 1. 符合 Vue 与 ECharts 用户的使用习惯；
 1. 提供纯函数 API，无副作用；
 1. 轻量级封装，简单易用；
-1. 支持图表大小自适应；
 
 
 ## 安装
@@ -23,8 +23,8 @@ npm i -S echarts-for-vue
 1. Vue 3
 ```javascript
 import { createApp, h } from 'vue';
-import * as echarts from 'echarts';
 import { plugin } from 'echarts-for-vue';
+import * as echarts from 'echarts';
 
 const app = createApp({ /*...*/ });
 app.use(plugin, { echarts, h });                        // 作为插件使用
@@ -35,19 +35,17 @@ app.use(plugin, { echarts, h });                        // 作为插件使用
 </template>
 
 <script>
+    import { createComponent } from 'echarts-for-vue';
     import * as echarts from 'echarts';
     import { h } from 'vue';
-    import { createComponent } from 'echarts-for-vue';
 
     export default {
         components: {
             ECharts: createComponent({ echarts, h }),   // 作为组件使用
         },
-        data() {
-            return {
-                option: { /*...*/ },
-            };
-        },
+        data: () => ({
+            option: { /*...*/ },
+        }),
         methods: {
             doSomething() {
                 this.$refs.chart.inst.getWidth();       // 调用 ECharts 实例的方法
@@ -60,8 +58,8 @@ app.use(plugin, { echarts, h });                        // 作为插件使用
 2. Vue 2
 ```javascript
 import Vue from 'vue';
-import * as echarts from 'echarts';
 import { plugin } from 'echarts-for-vue';
+import * as echarts from 'echarts';
 
 Vue.use(plugin, { echarts });                           // 作为插件使用
 ```
@@ -71,18 +69,16 @@ Vue.use(plugin, { echarts });                           // 作为插件使用
 </template>
 
 <script>
-    import * as echarts from 'echarts';
     import { createComponent } from 'echarts-for-vue';
+    import * as echarts from 'echarts';
 
     export default {
         components: {
             ECharts: createComponent({ echarts }),      // 作为组件使用
         },
-        data() {
-            return {
-                option: { /*...*/ },
-            };
-        },
+        data: () => ({
+            option: { /*...*/ },
+        }),
         methods: {
             doSomething() {
                 this.$refs.chart.inst.getWidth();       // 调用 ECharts 实例的方法
@@ -98,23 +94,24 @@ Vue.use(plugin, { echarts });                           // 作为插件使用
 ## 全局 API
 |定义|返回值|说明|
 |-|-|-|
-|`createComponent`(*initialOptions*: object): object|组件定义对象|创建组件|
-|`plugin`(*app*: Vue, *initialOptions*: object): void||插件的安装方法|
+|`createComponent`(*options*: Options): object|组件定义对象|创建组件|
+|`plugin`(*app*: Vue, *options*: Options): void||插件的安装方法|
 
 
-## initialOptions
+## Options
 |属性|类型|默认值|可选|说明|
 |-|-|-|-|-|
-|echarts|object|||ECharts 库的全局对象|
-|h|function||✔|Vue 的 `createElement` 方法（使用 Vue 3 时，是**必选**的）|
-|ResizeObserver|function|window.ResizeObserver|✔|全局 `ResizeObserver` 不存在时，可通过 <a href="https://github.com/que-etc/resize-observer-polyfill" target="_blank">polyfill</a> 提供支持|
+|echarts|typeof echarts|||ECharts 库的全局对象|
+|h|Function||✔|Vue 的 `createElement` 方法（使用 Vue 3 时，是**必选**的）|
+|ResizeObserver|typeof ResizeObserver|window.ResizeObserver|✔|全局 `ResizeObserver` 不存在时，可通过 <a href="https://github.com/que-etc/resize-observer-polyfill" target="_blank">polyfill</a> 提供支持|
 |name|string|"ECharts"|✔|组件的注册名称|
+|deepWatchOption|boolean|true|✔|深度监听属性 “option”|
 
 
 ## 实例属性
 |名称|类型|只读|说明|
 |-|-|-|-|
-|inst|object|✔|ECharts 实例|
+|inst|ECharts|✔|ECharts 实例|
 
 
 ## props
@@ -124,19 +121,25 @@ Vue.use(plugin, { echarts });                           // 作为插件使用
 |initOpts|object|||`echarts.init` 方法的入参 `opts`，<a href="https://echarts.apache.org/zh/api.html#echarts.init" target="_blank">详见</a>|
 |loading|boolean|false|✔|显示加载动画效果|
 |loadingType|string|"default"||ECharts 实例 `showLoading` 方法的入参 `type`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.showLoading" target="_blank">详见</a>|
-|loadingOpts|object|||ECharts 实例 `showLoading` 方法的入参 `opts`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.showLoading" target="_blank">详见</a>|
-|option|object||✔|ECharts 实例 `setOption` 方法的入参 `option`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.setOption" target="_blank">详见</a>|
-|setOptionOpts|object|||ECharts 实例 `setOption` 方法的入参 `opts`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.setOption" target="_blank">详见</a>|
-|events|Arguments[]|||数组元素为ECharts 实例 `on` 方法的入参，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.on" target="_blank">详见</a>|
-|autoResize|boolean|true|✔|自动调整大小（基于 `ResizeObserver` 实现，可通过 <a href="https://github.com/que-etc/resize-observer-polyfill" target="_blank">polyfill</a> 向前兼容）|
+|loadingOpts|EChartsLoadingOption |||ECharts 实例 `showLoading` 方法的入参 `opts`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.showLoading" target="_blank">详见</a>|
+|option|EChartOption||✔|ECharts 实例 `setOption` 方法的入参 `option`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.setOption" target="_blank">详见</a>|
+|optionOpts|EChartsOptionConfig|||ECharts 实例 `setOption` 方法的入参 `opts`，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.setOption" target="_blank">详见</a>|
+|events|Arguments[]|||数组元素为 ECharts 实例 `on` 方法的入参，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.on" target="_blank">详见</a>|
+|autoResize|boolean|true|✔|自动调整大小|
 
 ***除了上述 `props`，其余属性将被传递给组件的根元素，如：`style`、`class`、`onclick` 等***
 
 
+## 事件
+|名称|说明|
+|-|-|
+|resize|图表大小调整时触发|
+
+
 ## methods
 |定义|说明|
 |-|-|
-|`setOption`(*option*: object, *opts*: object): void|调用 ECharts 实例的 `setOption` 方法，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.setOption" target="_blank">详见</a>|
+|`setOption`(*option*: EChartOption, *opts*?: EChartsOptionConfig): void|调用 ECharts 实例的 `setOption` 方法，<a href="https://echarts.apache.org/zh/api.html#echartsInstance.setOption" target="_blank">详见</a>|
 |`resize`(): void|调整图表大小（以组件根元素大小为基准）|
 |`addResizeListener`(): void|添加 resize 监听器|
 |`removeResizeListener`(): void|移除 resize 监听器|

diff --git a/index.d.ts b/index.d.ts
@@ -1,15 +1,18 @@
 import * as echarts from 'echarts'
 
 
+type EChartsNS = typeof echarts
+type ResizeObserverConstructor = typeof ResizeObserver
 type Options = {
-    echarts: typeof echarts
+    echarts: EChartsNS
     h?: Function
-    ResizeObserver?: typeof ResizeObserver
+    ResizeObserver?: ResizeObserverConstructor
     name?: string
+    deepWatchOption?: boolean
 }
 
 
 declare module "echarts-for-vue" {
     export function createComponent(options: Options): object
-    export function plugin(app: any, options: Options): void
+    export function plugin(app: { component: Function }, options: Options): void
 }