[incubator-echarts-doc] branch next updated: doc: add doc for listen to events when click on blank.

[su...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sushuang pushed a commit to branch next
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-doc.git


The following commit(s) were added to refs/heads/next by this push:
     new 87eaf4e  doc: add doc for listen to events when click on blank.
87eaf4e is described below

commit 87eaf4efe897ec2ef0d225ca1a4741c090e7529c
Author: 100pah <su...@gmail.com>
AuthorDate: Tue Nov 17 19:52:05 2020 +0800

    doc: add doc for listen to events when click on blank.
---
 en/tutorial/event.md | 28 ++++++++++++++++++++++++++++
 zh/tutorial/event.md | 27 +++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/en/tutorial/event.md b/en/tutorial/event.md
index a152920..5adf721 100644
--- a/en/tutorial/event.md
+++ b/en/tutorial/event.md
@@ -238,6 +238,7 @@ myChart.on('legendselectchanged', function (params) {
 });
 ```
 
+
 ## Triggering Component Actions through Code in ECharts
 
 Actions like `'legendselectchanged'` mentioned above will be triggered by component interaction. Besides that, sometimes we need to trigger certain actions in our program, such as showing tooltip, or selecting legend.
@@ -249,3 +250,30 @@ Frequently used actions and the parameters are listed in [action](api.html#actio
 Below displays how to highlight each sector of pie chart in turn through `dispatchAction`.
 
 ~[600x400](${galleryViewPath}doc-example/pie-highlight&edit=1&reset=1)
+
+
+## Listen to events from the blank
+
+Sometimes developers need to listen to the events that are triggered from the blank of the canvas. For example, need to reset the chart when users click on the blank.
+
+Before we talk about this feature, we need to clarify two kinds of events: `zrender events` and `echarts events`.
+```js
+myChart.getZr().on('click', function (event) {
+    // This listener is listening to a `zrender event`.
+});
+myChart.on('click', function (event) {
+    // This listener is listening to a `echarts event`.
+});
+```
+`zrender events` are different from `echarts events`. The former one are triggered when mouse/pointer is at everywhere, while the latter one can only be triggered when mouse/pointer is at the graphic elements. In fact, `echarts events` are implemented based on `zrender events`, that is, when a `zrender events` is triggered at a graphic element, `echarts` will trigger a `echarts event`.
+
+Having `zrender events`, we can implement "listen to events from the blank" as follows:
+```js
+myChart.getZr().on('click', function (event) {
+    // No "target" means that mouse/pointer is not on
+    // any of the graphic elements, which is "blank".
+    if (!event.target) {
+        // Click on blank. Do something.
+    }
+});
+```
diff --git a/zh/tutorial/event.md b/zh/tutorial/event.md
index 421fb63..3c45e38 100644
--- a/zh/tutorial/event.md
+++ b/zh/tutorial/event.md
@@ -246,3 +246,30 @@ myChart.on('legendselectchanged', function (params) {
 下面示例演示了如何通过`dispatchAction`去轮流高亮饼图的每个扇形。
 
 ~[600x400](${galleryViewPath}doc-example/pie-highlight&edit=1&reset=1)
+
+
+## 监听“空白处”的事件
+
+有时候，开发者需要监听画布的“空白处”所触发的事件。比如，当需要在用户点击“空白处”的时候重置图表时。
+
+在讨论这个功能之前，我们需要先明确两种事件。`zrender 事件`和`echarts 事件`。
+
+```js
+myChart.getZr().on('click', function (event) {
+    // 该监听器正在监听一个`zrender 事件`。
+});
+myChart.on('click', function (event) {
+    // 该监听器正在监听一个`echarts 事件`。
+});
+```
+`zrender 事件`与`echarts 事件`不同。前者是当鼠标在任何地方都会被触发，而后者是只有当鼠标在图形元素上时才能被触发。事实上，`echarts 事件` 是在 `zrender 事件` 的基础上实现的，也就是说，当一个 `zrender 事件` 在图形元素上被触发时，`echarts` 将触发一个 `echarts 事件` 给开发者。
+
+有了 `zrender事件`，我们就可以实现 “监听空白处的事件”，具体如下：
+```js
+myChart.getZr().on('click', function (event) {
+    // 没有 target 意味着鼠标/指针不在任何一个图形元素上，它是从“空白处”触发的。
+    if (!event.target) {
+        // 点击在了空白处，做些什么。
+    }
+});
+```


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org