refactor: improve readability and add more comments to explain native event handling

Author: Justineo

README.md

@@ -319,6 +319,78 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/src/dem
 
   For performance critical scenarios (having a large dataset) we'd better bypass Vue's reactivity system for `option` prop. By specifying `manual-update` prop with `true` and not providing `option` prop, the dataset won't be watched any more. After doing so, you need to retrieve the component instance with `ref` and manually call `setOption` method to update the chart.
 
+### Events
+
+You can bind events with Vue's `v-on` directive.
+
+```vue
+<template>
+  <v-chart :option="option" @highlight="handleHighlight" />
+</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:
+
+- `highlight` [→](https://echarts.apache.org/en/api.html#events.highlight)
+- `downplay` [→](https://echarts.apache.org/en/api.html#events.downplay)
+- `selectchanged` [→](https://echarts.apache.org/en/api.html#events.selectchanged)
+- `legendselectchanged` [→](https://echarts.apache.org/en/api.html#events.legendselectchanged)
+- `legendselected` [→](https://echarts.apache.org/en/api.html#events.legendselected)
+- `legendunselected` [→](https://echarts.apache.org/en/api.html#events.legendunselected)
+- `legendselectall` [→](https://echarts.apache.org/en/api.html#events.legendselectall)
+- `legendinverseselect` [→](https://echarts.apache.org/en/api.html#events.legendinverseselect)
+- `legendscroll` [→](https://echarts.apache.org/en/api.html#events.legendscroll)
+- `datazoom` [→](https://echarts.apache.org/en/api.html#events.datazoom)
+- `datarangeselected` [→](https://echarts.apache.org/en/api.html#events.datarangeselected)
+- `timelinechanged` [→](https://echarts.apache.org/en/api.html#events.timelinechanged)
+- `timelineplaychanged` [→](https://echarts.apache.org/en/api.html#events.timelineplaychanged)
+- `restore` [→](https://echarts.apache.org/en/api.html#events.restore)
+- `dataviewchanged` [→](https://echarts.apache.org/en/api.html#events.dataviewchanged)
+- `magictypechanged` [→](https://echarts.apache.org/en/api.html#events.magictypechanged)
+- `geoselectchanged` [→](https://echarts.apache.org/en/api.html#events.geoselectchanged)
+- `geoselected` [→](https://echarts.apache.org/en/api.html#events.geoselected)
+- `geounselected` [→](https://echarts.apache.org/en/api.html#events.geounselected)
+- `axisareaselected` [→](https://echarts.apache.org/en/api.html#events.axisareaselected)
+- `brush` [→](https://echarts.apache.org/en/api.html#events.brush)
+- `brushEnd` [→](https://echarts.apache.org/en/api.html#events.brushEnd)
+- `brushselected` [→](https://echarts.apache.org/en/api.html#events.brushselected)
+- `globalcursortaken` [→](https://echarts.apache.org/en/api.html#events.globalcursortaken)
+- `rendered` [→](https://echarts.apache.org/en/api.html#events.rendered)
+- `finished` [→](https://echarts.apache.org/en/api.html#events.finished)
+- Mouse events
+  - `click` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.click)
+  - `dblclick` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.dblclick)
+  - `mouseover` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mouseover)
+  - `mouseout` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mouseout)
+  - `mousemove` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mousemove)
+  - `mousedown` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mousedown)
+  - `mouseup` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mouseup)
+  - `globalout` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.globalout)
+  - `contextmenu` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.contextmenu)
+- ZRender events
+  - `zr:click`
+  - `zr:mousedown`
+  - `zr:mouseup`
+  - `zr:mousewheel`
+  - `zr:dblclick`
+  - `zr:contextmenu`
+
+See supported events [here →](https://echarts.apache.org/en/api.html#events)
+
+#### Native DOM Events
+
+As Vue-ECharts binds events to the ECharts instance by default, there is some caveat when using native DOM events. You need to prefix the event name with `native:` to bind native DOM events (or you can use the `.native` modifier in Vue 2, which is dropped in Vue 3).
+
+```vue
+<template>
+  <v-chart @native:click="handleClick" />
+</template>
+```
+
 ### Provide / Inject
 
 Vue-ECharts provides provide/inject API for `theme`, `init-options`, `update-options` and `loading-options` to help configuring contextual options. eg. for `init-options` you can use the provide API like this:
@@ -402,76 +474,6 @@ import { THEME_KEY } from 'vue-echarts'
 
 Static methods can be accessed from [`echarts` itself](https://echarts.apache.org/en/api.html#echarts).
 
-### Events
-
-You can bind events with Vue's `v-on` directive.
-
-```vue
-<template>
-  <v-chart :option="option" @highlight="handleHighlight" />
-</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:
-
-- `highlight` [→](https://echarts.apache.org/en/api.html#events.highlight)
-- `downplay` [→](https://echarts.apache.org/en/api.html#events.downplay)
-- `selectchanged` [→](https://echarts.apache.org/en/api.html#events.selectchanged)
-- `legendselectchanged` [→](https://echarts.apache.org/en/api.html#events.legendselectchanged)
-- `legendselected` [→](https://echarts.apache.org/en/api.html#events.legendselected)
-- `legendunselected` [→](https://echarts.apache.org/en/api.html#events.legendunselected)
-- `legendselectall` [→](https://echarts.apache.org/en/api.html#events.legendselectall)
-- `legendinverseselect` [→](https://echarts.apache.org/en/api.html#events.legendinverseselect)
-- `legendscroll` [→](https://echarts.apache.org/en/api.html#events.legendscroll)
-- `datazoom` [→](https://echarts.apache.org/en/api.html#events.datazoom)
-- `datarangeselected` [→](https://echarts.apache.org/en/api.html#events.datarangeselected)
-- `timelinechanged` [→](https://echarts.apache.org/en/api.html#events.timelinechanged)
-- `timelineplaychanged` [→](https://echarts.apache.org/en/api.html#events.timelineplaychanged)
-- `restore` [→](https://echarts.apache.org/en/api.html#events.restore)
-- `dataviewchanged` [→](https://echarts.apache.org/en/api.html#events.dataviewchanged)
-- `magictypechanged` [→](https://echarts.apache.org/en/api.html#events.magictypechanged)
-- `geoselectchanged` [→](https://echarts.apache.org/en/api.html#events.geoselectchanged)
-- `geoselected` [→](https://echarts.apache.org/en/api.html#events.geoselected)
-- `geounselected` [→](https://echarts.apache.org/en/api.html#events.geounselected)
-- `axisareaselected` [→](https://echarts.apache.org/en/api.html#events.axisareaselected)
-- `brush` [→](https://echarts.apache.org/en/api.html#events.brush)
-- `brushEnd` [→](https://echarts.apache.org/en/api.html#events.brushEnd)
-- `brushselected` [→](https://echarts.apache.org/en/api.html#events.brushselected)
-- `globalcursortaken` [→](https://echarts.apache.org/en/api.html#events.globalcursortaken)
-- `rendered` [→](https://echarts.apache.org/en/api.html#events.rendered)
-- `finished` [→](https://echarts.apache.org/en/api.html#events.finished)
-- Mouse events
-  - `click` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.click)
-  - `dblclick` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.dblclick)
-  - `mouseover` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mouseover)
-  - `mouseout` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mouseout)
-  - `mousemove` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mousemove)
-  - `mousedown` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mousedown)
-  - `mouseup` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.mouseup)
-  - `globalout` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.globalout)
-  - `contextmenu` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.contextmenu)
-- ZRender events
-  - `zr:click`
-  - `zr:mousedown`
-  - `zr:mouseup`
-  - `zr:mousewheel`
-  - `zr:dblclick`
-  - `zr:contextmenu`
-
-See supported events [here →](https://echarts.apache.org/en/api.html#events)
-
-#### Native DOM Events
-
-```vue
-<template>
-  <v-chart @native:click="handleClick" />
-</template>
-```
-
 ## CSP: `style-src` or `style-src-elem`
 
 If you are applying a CSP to prevent inline `<style>` injection, you need to use files from `dist/csp` directory and include `dist/csp/style.css` into your app manually.

README.zh-Hans.md

@@ -381,6 +381,16 @@ Vue-ECharts 支持如下事件：
 
 请参考支持的事件列表。[前往 →](https://echarts.apache.org/zh/api.html#events)
 
+#### 原生 DOM 事件
+
+由于 Vue-ECharts 默认将事件绑定到 ECharts 实例，因此在使用原生 DOM 事件时需要做一些特殊处理。你需要在事件名称前加上 `native:` 前缀来绑定原生 DOM 事件（可以在 Vue 2 中也可以使用 `.native` 修饰符，但这在 Vue 3 中已被废弃）。
+
+```vue
+<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` 提供上下文配置：
@@ -464,6 +474,8 @@ import { THEME_KEY } from 'vue-echarts'
 
 静态方法请直接通过 [`echarts` 本身](https://echarts.apache.org/zh/api.html#echarts)进行调用。
 
+
+
 ## CSP: `style-src` 或 `style-src-elem`
 
 如果你正在应用 CSP 来防止内联 `<style>` 注入，则需要使用 `dist/csp` 目录中的文件，并手动引入 `dist/csp/style.css`。

src/ECharts.ts

@@ -55,6 +55,8 @@ export const UPDATE_OPTIONS_KEY =
   "ecUpdateOptions" as unknown as InjectionKey<UpdateOptionsInjection>;
 export { LOADING_OPTIONS_KEY } from "./composables";
 
+const NATIVE_EVENT_RE = /(^&?~?!?)native:/;
+
 export default defineComponent({
   name: "echarts",
   props: {
@@ -95,7 +97,7 @@ export default defineComponent({
       () => props.updateOptions || unwrapInjected(defaultUpdateOptions, {})
     );
     const nonEventAttrs = computed(() => omitOn(attrs));
-    const nativeEventAttrs: Record<string, unknown> = {};
+    const nativeListeners: Record<string, unknown> = {};
 
     // @ts-expect-error listeners for Vue 2 compatibility
     const listeners = getCurrentInstance().proxy.$listeners;
@@ -116,7 +118,14 @@ export default defineComponent({
       }
 
       const realListeners: Record<string, any> = {};
+
       if (!listeners) {
+        // This is for Vue 3.
+        // We are converting all `on<Event>` props to event listeners compatible with Vue 2
+        // and collect them into `realListeners` so that we can bind them to the chart instance
+        // later in the same way.
+        // For `onNative:<event>` props, we just strip the `Native:` part and collect them into
+        // `nativeListeners` so that we can bind them to the root element directly.
         Object.keys(attrs)
           .filter(key => isOn(key))
           .forEach(key => {
@@ -125,12 +134,13 @@ export default defineComponent({
             let event = key.charAt(2).toLowerCase() + key.slice(3);
 
             // Collect native DOM events
-            if (event.startsWith("native:")) {
+            if (event.indexOf("native:") === 0) {
               // native:click -> onClick
-              const nativeKey =
-                "on" + event.charAt(7).toUpperCase() + event.slice(8);
+              const nativeKey = `on${event
+                .charAt(7)
+                .toUpperCase()}${event.slice(8)}`;
 
-              nativeEventAttrs[nativeKey] = attrs[key];
+              nativeListeners[nativeKey] = attrs[key];
               return;
             }
 
@@ -143,13 +153,18 @@ export default defineComponent({
             realListeners[event] = attrs[key];
           });
       } else {
+        // This is for Vue 2.
+        // We just need to distinguish normal events and `native:<event>` events and
+        // collect them into `realListeners` and `nativeListeners` respectively.
+        // For `native:<event>` events, we just strip the `native:` part and collect them
+        // into `nativeListeners` so that we can bind them to the root element directly.
         // native:click   -> click
         // ~native:click  -> ~click
         // &~!native:click -> &~!click
-        const regex = /(^&?~?!?)native:/;
         Object.keys(listeners).forEach(key => {
-          if (regex.test(key)) {
-            nativeEventAttrs[key.replace(regex, "$1")] = listeners[key];
+          if (NATIVE_EVENT_RE.test(key)) {
+            nativeListeners[key.replace(NATIVE_EVENT_RE, "$1")] =
+              listeners[key];
           } else {
             realListeners[key] = listeners[key];
           }
@@ -317,7 +332,7 @@ export default defineComponent({
       inner,
       setOption,
       nonEventAttrs,
-      nativeEventAttrs,
+      nativeListeners,
       ...publicApi
     };
   },
@@ -326,8 +341,8 @@ export default defineComponent({
     // See https://v3-migration.vuejs.org/breaking-changes/render-function-api.html#vnode-props-format
     const attrs = (
       Vue2
-        ? { attrs: this.nonEventAttrs, on: this.nativeEventAttrs }
-        : { ...this.nonEventAttrs, ...this.nativeEventAttrs }
+        ? { attrs: this.nonEventAttrs, on: this.nativeListeners }
+        : { ...this.nonEventAttrs, ...this.nativeListeners }
     ) as any;
     attrs.ref = "root";
     attrs.class = attrs.class ? ["echarts"].concat(attrs.class) : "echarts";