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 <sushuang0...@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-unsubscr...@echarts.apache.org
For additional commands, e-mail: commits-h...@echarts.apache.org
