feat: make it possible to dynamically change provide values for Vue 2

Author: Justineo

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 6.3.0
+
+* Injected values can now be wrapped in an object so that they can be reactive in Vue 2.
+
 ## 6.2.4
 
 * Fixed that attributes were not outputted onto the chart root element for Vue 2 (#670).

README.md

@@ -399,16 +399,16 @@ Vue-ECharts provides provide/inject API for `theme`, `init-options`, `update-opt
 <summary>Vue 3</summary>
 
 ```js
-import { INIT_OPTIONS_KEY } from 'vue-echarts'
+import { THEME_KEY } from 'vue-echarts'
 import { provide } from 'vue'
 
 // composition API
-provide(INIT_OPTIONS_KEY, ...)
+provide(THEME_KEY, 'dark')
 
 // options API
 {
   provide: {
-    [INIT_OPTIONS_KEY]: { ... }
+    [THEME_KEY]: 'dark'
   }
 }
 ```
@@ -419,16 +419,35 @@ provide(INIT_OPTIONS_KEY, ...)
 <summary>Vue 2</summary>
 
 ```js
-import { INIT_OPTIONS_KEY } from 'vue-echarts'
+import { THEME_KEY } from 'vue-echarts'
 
 // in component options
 {
   provide: {
-    [INIT_OPTIONS_KEY]: { ... }
+    [THEME_KEY]: 'dark'
   }
 }
 ```
 
+> **Note**
+>
+> You need to provide an object for Vue 2 if you want to change it dynamically.
+>
+> ```js
+> // in component options
+> {
+>   data () {
+>     return {
+>       theme: { value: 'dark' }
+>     }
+>   },
+>   provide () {
+>     return {
+>       [THEME_KEY]: this.theme
+>     }
+>   }
+> }
+> ```
 </details>
 
 ### Methods
@@ -464,6 +483,8 @@ You can bind events with Vue's `v-on` directive.
 </template>
 ```
 
+> **Note**
+>
 > Only the `.once` event modifier is supported as other modifiers are tightly coupled with the DOM event system.
 
 Vue-ECharts support the following events:

README.zh-Hans.md

@@ -400,6 +400,8 @@ Vue.component("v-chart", VueECharts);
 </template>
 ```
 
+> **Note**
+>
 > 仅支持 `.once` 修饰符，因为其它修饰符都与 DOM 事件机制强耦合。
 
 Vue-ECharts 支持如下事件：
@@ -458,16 +460,16 @@ Vue-ECharts 为 `theme`、`init-options`、`update-options` 和 `loading-options
 <summary>Vue 3</summary>
 
 ```js
-import { INIT_OPTIONS_KEY } from 'vue-echarts'
+import { THEME_KEY } from 'vue-echarts'
 import { provide } from 'vue'
 
-// composition API
-provide(INIT_OPTIONS_KEY, ...)
+// 组合式 API
+provide(THEME_KEY, 'dark')
 
-// options API
+// 选项式 API
 {
   provide: {
-    [INIT_OPTIONS_KEY]: { ... }
+    [THEME_KEY]: 'dark'
   }
 }
 ```
@@ -478,16 +480,35 @@ provide(INIT_OPTIONS_KEY, ...)
 <summary>Vue 2</summary>
 
 ```js
-import { INIT_OPTIONS_KEY } from 'vue-echarts'
+import { THEME_KEY } from 'vue-echarts'
 
-// in component options
+// 组件选项中
 {
   provide: {
-    [INIT_OPTIONS_KEY]: { ... }
+    [THEME_KEY]: 'dark'
   }
 }
 ```
 
+> **Note**
+>
+> 在 Vue 2 中，如果你想动态地改变这些选项，那么你需要提供一个对象。
+>
+> ```js
+> // 组件选项中
+> {
+>   data () {
+>     return {
+>       theme: { value: 'dark' }
+>     }
+>   },
+>   provide () {
+>     return {
+>       [THEME_KEY]: this.theme
+>     }
+>   }
+> }
+> ```
 </details>
 
 ### 方法

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-echarts",
-  "version": "6.2.4",
+  "version": "6.3.0",
   "description": "Vue.js component for Apache ECharts.",
   "author": "GU Yiling <[email protected]>",
   "scripts": {
@@ -62,7 +62,7 @@
     "tslib": "^2.4.0",
     "typescript": "4.6.4",
     "vue": "^3.2.33",
-    "vue2": "npm:vue@^2.7.4",
+    "vue2": "npm:vue@^2.7.14",
     "webpack": "^5.72.1"
   },
   "peerDependencies": {

pnpm-lock.yaml

@@ -2,7 +2,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import {
   defineComponent,
-  unref,
   shallowRef,
   toRefs,
   watch,
@@ -37,7 +36,7 @@ import {
   useLoading,
   loadingProps
 } from "./composables";
-import { omitOn } from "./utils";
+import { omitOn, unwrapInjected } from "./utils";
 import "./style.css";
 
 const TAG_NAME = "x-vue-echarts";
@@ -81,12 +80,14 @@ export default defineComponent({
     const realOption = computed(
       () => manualOption.value || props.option || null
     );
-    const realTheme = computed(() => props.theme || unref(defaultTheme) || {});
+    const realTheme = computed(
+      () => props.theme || unwrapInjected(defaultTheme, {})
+    );
     const realInitOptions = computed(
-      () => props.initOptions || unref(defaultInitOptions) || {}
+      () => props.initOptions || unwrapInjected(defaultInitOptions, {})
     );
     const realUpdateOptions = computed(
-      () => props.updateOptions || unref(defaultUpdateOptions) || {}
+      () => props.updateOptions || unwrapInjected(defaultUpdateOptions, {})
     );
     const nonEventAttrs = computed(() => omitOn(attrs));
 

src/ECharts.ts

@@ -1,10 +1,11 @@
+import { unwrapInjected } from "src/utils";
 import {
   inject,
   unref,
   computed,
-  Ref,
   watchEffect,
-  InjectionKey
+  type Ref,
+  type InjectionKey
 } from "vue-demi";
 import { EChartsType } from "../types";
 
@@ -22,7 +23,7 @@ export function useLoading(
 ): void {
   const defaultLoadingOptions = inject(LOADING_OPTIONS_KEY, {});
   const realLoadingOptions = computed(() => ({
-    ...unref(defaultLoadingOptions),
+    ...unwrapInjected(defaultLoadingOptions, {}),
     ...loadingOptions?.value
   }));
 

src/composables/loading.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/ban-types */
-import { Ref, DefineComponent } from "vue-demi";
-import { Option, InitOptions, UpdateOptions, EChartsType } from "./types";
+import type { Ref, DefineComponent } from "vue-demi";
+import type { Option, InitOptions, UpdateOptions, EChartsType } from "./types";
 
 declare const LOADING_OPTIONS_KEY = "ecLoadingOptions";
 declare const THEME_KEY = "ecTheme";

src/index.vue2.d.ts

@@ -1,21 +1,21 @@
-import { init, SetOptionOpts } from "echarts/core";
-import { Ref } from "vue";
+import { init, type SetOptionOpts } from "echarts/core";
+import type { Ref } from "vue";
+
+export type Injection<T> = T | null | Ref<T | null> | { value: T | null };
 
 type InitType = typeof init;
 export type InitParameters = Parameters<InitType>;
 export type Theme = NonNullable<InitParameters[1]>;
-export type ThemeInjection = Theme | null | Ref<Theme | null>;
+export type ThemeInjection = Injection<Theme>;
 export type InitOptions = NonNullable<InitParameters[2]>;
-export type InitOptionsInjection = InitOptions | null | Ref<InitOptions | null>;
+
+export type InitOptionsInjection = Injection<InitOptions>;
+
+export type UpdateOptions = SetOptionOpts;
+export type UpdateOptionsInjection = Injection<UpdateOptions>;
 
 export type EChartsType = ReturnType<InitType>;
 type ZRenderType = ReturnType<EChartsType["getZr"]>;
 export type EventTarget = EChartsType | ZRenderType;
 type SetOptionType = EChartsType["setOption"];
 export type Option = Parameters<SetOptionType>[0];
-
-export type UpdateOptions = SetOptionOpts;
-export type UpdateOptionsInjection =
-  | UpdateOptions
-  | null
-  | Ref<UpdateOptions | null>;

src/types.ts

@@ -1,3 +1,6 @@
+import { unref } from "vue-demi";
+import type { Injection } from "./types";
+
 type Attrs = {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [key: string]: any;
@@ -18,3 +21,16 @@ export function omitOn(attrs: Attrs): Attrs {
 
   return result;
 }
+
+export function unwrapInjected<T, V>(
+  injection: Injection<T>,
+  defaultValue: V
+): T | V {
+  const value = unref(injection);
+
+  if (value && typeof value === "object" && "value" in value) {
+    return value.value || defaultValue;
+  }
+
+  return value || defaultValue;
+}