This is an automated email from the ASF dual-hosted git repository.
sushuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-handbook.git
The following commit(s) were added to refs/heads/master by this push:
new 6f5f973 doc: add doc for listen to click on blank.
6f5f973 is described below
commit 6f5f9731b41a49f3c2e75cfc53fff567d829aefa
Author: 100pah <[email protected]>
AuthorDate: Tue Nov 17 19:58:26 2020 +0800
doc: add doc for listen to click on blank.
---
contents/en/concepts/event.md | 27 +++++++++++++++++++++++++++
contents/zh/concepts/event.md | 28 ++++++++++++++++++++++++++++
2 files changed, 55 insertions(+)
diff --git a/contents/en/concepts/event.md b/contents/en/concepts/event.md
index 8013516..6c8866b 100644
--- a/contents/en/concepts/event.md
+++ b/contents/en/concepts/event.md
@@ -253,3 +253,30 @@ Commonly used behavior and corresponding parameters were
listed in [action](${ma
The following example shows how to highlight each sector one by one in the pie
chart using `dispatchAction`.
<iframe width="600" height="400"
src="${exampleViewPath}doc-example/pie-highlight&reset=1&edit=1"></iframe>
+
+
+## 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/contents/zh/concepts/event.md b/contents/zh/concepts/event.md
index 2146045..202283b 100644
--- a/contents/zh/concepts/event.md
+++ b/contents/zh/concepts/event.md
@@ -251,3 +251,31 @@ myChart.on('legendselectchanged', function (params) {
下面示例演示了如何通过 `dispatchAction` 去轮流高亮饼图的每个扇形。
<iframe width="600" height="400"
src="${exampleViewPath}doc-example/pie-highlight&reset=1&edit=1"></iframe>
+
+
+## 监听“空白处”的事件
+
+有时候，开发者需要监听画布的“空白处”所触发的事件。比如，当需要在用户点击“空白处”的时候重置图表时。
+
+在讨论这个功能之前，我们需要先明确两种事件。`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: [email protected]
For additional commands, e-mail: [email protected]
