[05/10] incubator-weex-site git commit: update event bubbling intro.

Mon, 26 Mar 2018 05:51:13 -0700 

update event bubbling intro.


Project: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/repo
Commit: 
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/commit/f1ddc1ec
Tree: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/tree/f1ddc1ec
Diff: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/diff/f1ddc1ec

Branch: refs/heads/master
Commit: f1ddc1ec789abff90bc34438623a63bc53212dd3
Parents: 38839e7
Author: MrRaindrop <[email protected]>
Authored: Mon Mar 26 17:57:16 2018 +0800
Committer: MrRaindrop <[email protected]>
Committed: Mon Mar 26 17:57:16 2018 +0800

----------------------------------------------------------------------
 source/cn/wiki/event-bubble.md | 148 ++++++++----------------------------
 source/wiki/event-bubble.md    | 148 ++++++++----------------------------
 2 files changed, 66 insertions(+), 230 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/f1ddc1ec/source/cn/wiki/event-bubble.md
----------------------------------------------------------------------
diff --git a/source/cn/wiki/event-bubble.md b/source/cn/wiki/event-bubble.md
index 964eab5..f44748a 100644
--- a/source/cn/wiki/event-bubble.md
+++ b/source/cn/wiki/event-bubble.md
@@ -8,142 +8,60 @@ version: 2.1
 
 <!-- toc -->
 
-> 仅在 <span class="api-version">v0.13</span> 及以上版本中支持。
+<span class="api-version">v0.13+</span>
 
-Weex 2.0 实现了 W3C 标准的事件冒泡机制。
+> **Note:** 目前仅 Weex Native（Android 和 iOS）支持，[web 
端](https://github.com/weexteam/weex-vue-render) 暂时不支持此项特性.
 
-### 使用
+如果你是个 web 开发者，你
大概对浏览器事件冒泡机制已经很熟悉了，而且可能认为 
Weex 默认会支持事件冒泡。然而，Weex 在 0.13 
之前是不支持这一特性的，在 0.13 版本，Weex 
提供了这项支持。
 
-```html
-<template>
-  <div class="root" @click="rootClick" bubble="true">
-    <text style="font-size: 40px;">{{rootText}}</text>
-    <div class="outer" @click="parentClick">
-      <div>
-        <text style="font-size: 40px;">{{parentText}}</text>
-      </div>
-      <text class="inner" @click="click">{{innerText}}</text>
-    </div>
-  </div>
-</template>
+对于不熟悉事件冒泡的开发者
，这里简要介绍一下浏览器事件冒泡机制的概念：
 
-<script>
-  module.exports = {
-    data: {
-      innerText: 'click me',
-      parentText: '',
-      rootText: ''
-    },
-    methods: {
-      click: function(e) {
-        this.innerText = 'inner bubble'
-      },
-      parentClick: function(e) {
-        this.parentText = 'parent bubble'
-      },
-      rootClick: function(e) {
-        this.rootText = 'root bubble'
-      }
-    }
-  }
-</script>
-
-<style scoped>
-  .inner {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a9b1b;
-    padding: 40px;
-  }
+## 概念
 
-  .outer {
-    font-size: 40px;
-    text-align: center;
-    background-color: #9b7a1b;
-    padding: 120px;
-  }
+以点击事件为例，比如一个点击事件发生在某个 `<video>` å…
ƒç´ ä¸Šï¼Œè¿™ä¸ªå…ƒç´ æœ‰ä¸€ä¸ªçˆ¶å…ƒç´ ï¼ˆæ¯”如是个 `div` 元素
），浏览器会执行两个处理阶段 - 
捕获（capturing）阶段和冒泡（bubbling）阶段。在 web 
开发中冒泡阶段会用的比较多，而捕获处理用的比较少。
 
-  .root {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a1b9b;
-    padding: 80px;
-  }
-</style>
-```
+在捕获阶段，浏览器检查当前元素的最外层父节点（在 web 
上，比如，`<html>` 元素），如果它上面绑定了一个 click 
事件处理器，那么先执行这个处理器。然后检查下一个元素
，`<html>` 的子元素里是 `<video>` 祖先元素的那个元素，做同æ 
·çš„检测。一步步直到遇到当前点击的这个元素本身。
 
-[try it](http://dotwe.org/vue/fa2957ce3e9eb47ad9ae1da22d845e95)
+接下来是冒泡阶段，方向和捕获阶段相反：浏览器å…
ˆæ£€æµ‹å½“前被点击的元素
上是否注册了点击事件处理器，如果有则执行它。接下来检测它的父å
…ƒç´ ï¼Œä¸€æ­¥æ­¥å‘上，直到最外层 `<html>` 元素。
 
-运行以上代码，用客户端打开，点击中间的元素
，可以看到事件向上传播，依次触发。
+![事件冒泡机制](https://mdn.mozillademos.org/files/14075/bubbling-capturing.png)
 
-### 注意
+我们一般使用默认的事件注册机制，将事件处理注册在冒泡阶段，所以处理冒泡阶段的æƒ
…
况比较多。当我们想要停止事件冒泡，只需要调用事件对象的
 `stopPropagation` 方法。标准事件对象包含 `stopPropagation` 
方法，当执行事件处理器时调用该方法，会立即停止事件冒泡，这æ
 ·äº‹ä»¶å†’泡处理链上的后续处理器就不会再执行下去。
 
-需要注意的是: ** 为了兼容之前的版本，Weex 
默认不会开启事件冒泡机制。需要在根元素的属性上，添加 
`bubble="true"` 来开启冒泡机制。否则，将不会向上传
播事件，保持与之前版本的效果相同。 **
+Weex 在 0.13 版本 SDK 
里实现了事件冒泡机制。注意事件冒泡默认是不开启的，你
需要在模板根元素上加上属性 `bubble=true` 才能开启冒泡。
 
-### stopPropagation
+## 使用
 
-在事件处理函数中，可以使用 `e.stopPropagation()` 
方法，来阻止本次事件向上的传
递过程。注意，`e.stopPropagation()` 与 `bubble="true"` 不同，前者
只会影响当前元素以及父元素的传播，不会影响子元素的传
播；后者是为了版本兼容而增加的开关机制，会全局å…
³é—­æˆ–者开启冒泡机制，两者可以共同存在使用，如下：
+事件冒泡默认不开启，需要手动添加 `bubble=true` 属性到根å…
ƒç´ ä¸Šã€‚
 
 ```html
 <template>
-  <div class="root" @click="rootClick" bubble="true">
-    <text style="font-size: 40px;">{{rootText}}</text>
-    <div class="outer" @click="parentClick">
-      <div>
-        <text style="font-size: 40px;">{{parentText}}</text>
-      </div>
-      <text class="inner" @click="click">{{innerText}}</text>
-    </div>
+  <!-- 开启事件冒泡机制. -->
+  <div bubble="true">
+    ...
   </div>
 </template>
+```
 
-<script>
-  module.exports = {
-    data: {
-      innerText: 'click me',
-      parentText: '',
-      rootText: ''
-    },
-    methods: {
-      click: function(e) {
-        this.innerText = 'inner bubble'
-      },
-      parentClick: function(e) {
-        this.parentText = 'parent bubble'
-        e.stopPropagation()
-      },
-      rootClick: function(e) {
-        this.rootText = 'root bubble'
-        // e.stopPropagation()
-      }
-    }
-  }
-</script>
-
-<style scoped>
-  .inner {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a9b1b;
-    padding: 40px;
-  }
+## 阻止冒泡
 
-  .outer {
-    font-size: 40px;
-    text-align: center;
-    background-color: #9b7a1b;
-    padding: 120px;
-  }
+在事件处理函数里，可以通过调用 `event.stopPropagation` 
方法阻止事件冒泡。这个方法和 [DOM æ 
‡å‡†](https://dom.spec.whatwg.org/#dom-event-stoppropagation)里的方法一致。注意
 `event.stopPropagation` 和 `bubble=true` 的影响范围不同，前者仅
针对当前冒泡到的元素以及其祖先层级有效，而对子元素无
效。而后者相当于一个全局开关，开启以后对该根元素内
部所有子元素都开启了事件冒泡效果。两者可以同时存在。
 
-  .root {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a1b9b;
-    padding: 80px;
+```javascript
+{
+  handleClick (event) {
+    // stop event propagation.
+    event.stopPropagation()
   }
-</style>
+}
 ```
 
-[try it](http://dotwe.org/vue/2cc80e19c9b2430fb780234628065a69)
+## 注意
+
+需要注意的是: **为了兼容之前的版本，Weex 
默认不会开启事件冒泡机制。需要在根元素的属性上，添加 
`bubble="true"` 来开启冒泡机制。否则，将不会向上传
播事件，保持与之前版本的效果相同。**
+
+## 实例
+
+[开启事件冒泡](http://dotwe.org/vue/fa2957ce3e9eb47ad9ae1da22d845e95)：使用
 Weex playground App 扫描页面里的二维ç 
ï¼Œç„¶åŽåœ¨æ‰“开页面中点击包含 'click me' 
文字的方框，会看到事件冒泡效果，即外层的组件依次显示事件成功冒泡到当前组件的提示。
 
-运行以上代码，用客户端打开，点击中间的元素
，可以看到事件向上传播到父元素被终止，不再继续往根å…
ƒç´ ä¼ æ’­ã€‚
+[阻止冒泡](http://dotwe.org/vue/2cc80e19c9b2430fb780234628065a69)：使用 
Weex playground App 扫描页面里的二维ç 
ï¼Œç„¶åŽåœ¨æ‰“开页面中点击包含 'click me' 
文字的方框，可以看到事件冒泡被父组件中断了，不再冒泡到最外层组件。

http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/f1ddc1ec/source/wiki/event-bubble.md
----------------------------------------------------------------------
diff --git a/source/wiki/event-bubble.md b/source/wiki/event-bubble.md
index 261266a..f470a7e 100644
--- a/source/wiki/event-bubble.md
+++ b/source/wiki/event-bubble.md
@@ -8,142 +8,60 @@ version: 2.1
 
 <!-- toc -->
 
-# Event Bubble <span class="api-version">v0.13+</span>
+<span class="api-version">v0.13+</span>
 
-Weex 2.0 implements the W3C standard event bubbling mechanism.
+> **Note:** This feature works only on weex's native platforms (i.e., on 
Android and iOS), but not on the web with latest [web 
renderer](https://github.com/weexteam/weex-vue-render) yet.
 
-### Usage
+If you are a web developer, then you are probably familiar with the event 
bubbling mechanism, and you may expect Weex to work the same way. However, Weex 
didn't implement this mechiansim util version 0.13.
 
-```html
-<template>
-  <div class="root" @click="rootClick" bubble="true">
-    <text style="font-size: 40px;">{{rootText}}</text>
-    <div class="outer" @click="parentClick">
-      <div>
-        <text style="font-size: 40px;">{{parentText}}</text>
-      </div>
-      <text class="inner" @click="click">{{innerText}}</text>
-    </div>
-  </div>
-</template>
+To those developers who are not familiar with the event bubbling, Here are 
some explanations about it, and the concept is rather easy.
 
-<script>
-  module.exports = {
-    data: {
-      innerText: 'click me',
-      parentText: '',
-      rootText: ''
-    },
-    methods: {
-      click: function(e) {
-        this.innerText = 'inner bubble'
-      },
-      parentClick: function(e) {
-        this.parentText = 'parent bubble'
-      },
-      rootClick: function(e) {
-        this.rootText = 'root bubble'
-      }
-    }
-  }
-</script>
-
-<style scoped>
-  .inner {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a9b1b;
-    padding: 40px;
-  }
+## Concept
 
-  .outer {
-    font-size: 40px;
-    text-align: center;
-    background-color: #9b7a1b;
-    padding: 120px;
-  }
+Take clicking as a example. When a click event fired on a `<video>` element 
that has a parent element (e.g. a parent `div` component), web browsers run two 
different phases - the capturing phase and the bubbling phase. We use bubbling 
phase a lot in web development, and use capturing less.
 
-  .root {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a1b9b;
-    padding: 80px;
-  }
-</style>
-```
+In the capturing phase, The browser checks to see if the element's outer-most 
ancestor (on web, may be a `<html>`) has an corresponding event handler 
registered on it, and runs it if so. Then it moves on to the next element 
inside `<html>` and does the same thing, then the next one, and so on until it 
reaches the element that was actually clicked on.
 
-[try it](http://dotwe.org/vue/fa2957ce3e9eb47ad9ae1da22d845e95)
+In the bubbling phase, the exact opposite occurs: The browser checks to see if 
the element that was actually clicked on has an onclick event handler 
registered on it in the bubbling phase, and runs it if so. Then it moves on to 
the next immediate ancestor element and does the same thing, then the next one, 
and so on until it reaches the `<html>` element.
 
-Run the above code, open with the client, click on the middle of the elements, 
you can see the event spread up, followed by the trigger.
+![event bubbling 
concept](https://mdn.mozillademos.org/files/14075/bubbling-capturing.png)
 
-### Notice
+We usually register our event listeners on the bubbling phase, so that we use 
bubbling a lot. But if you want to turn this off, you can use `stopPropagation` 
method of the event object. The standard event object has a function available 
on it called `stopPropagation`, which when invoked on a handler's event object 
makes it so that handler is run, but the event doesn't bubble any further up 
the chain, so no more handlers will be run.
 
-One thing should be noticed: **For compatibility with previous versions, Weex 
does not turn on event bubbling by default. You need to add `bubble = "true"` 
on the root element's properties to turn on the bubbling mechanism. Otherwise, 
the event will not be propagated upwards, keeping the same effect as the 
previous version.**
+Weex implemented this event bubbling phase in the 0.13 SDK, and for the 
record, the event bubbling phase is not enabled by default - You should use a 
attribute `bubble=true` on the root element to turn this feature on.
 
-### stopPropagation
+## How To Use
 
-In the event handler function, you can use the `e.stopPropagation()` method to 
prevent the event from escalating. Note that `e.stopPropagation()` differs from 
`bubble = "true"`, which affects only the current elements and the propagation 
of parent elements, without affecting the propagation of child elements; the 
latter is a switching mechanism that is added for compatibility, Will be a 
global shutdown or open the bubble mechanism, the two can co-exist, as follows:
+The event bubbling is not enabled by default, you should use `bubble="true"` 
in the root element to turn it on.
 
 ```html
 <template>
-  <div class="root" @click="rootClick" bubble="true">
-    <text style="font-size: 40px;">{{rootText}}</text>
-    <div class="outer" @click="parentClick">
-      <div>
-        <text style="font-size: 40px;">{{parentText}}</text>
-      </div>
-      <text class="inner" @click="click">{{innerText}}</text>
-    </div>
+  <!-- Use it in the root element to turn it on. -->
+  <div bubble="true">
+    ...
   </div>
 </template>
+```
 
-<script>
-  module.exports = {
-    data: {
-      innerText: 'click me',
-      parentText: '',
-      rootText: ''
-    },
-    methods: {
-      click: function(e) {
-        this.innerText = 'inner bubble'
-      },
-      parentClick: function(e) {
-        this.parentText = 'parent bubble'
-        e.stopPropagation()
-      },
-      rootClick: function(e) {
-        this.rootText = 'root bubble'
-        // e.stopPropagation()
-      }
-    }
-  }
-</script>
-
-<style scoped>
-  .inner {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a9b1b;
-    padding: 40px;
-  }
+## Stop Bubbling
 
-  .outer {
-    font-size: 40px;
-    text-align: center;
-    background-color: #9b7a1b;
-    padding: 120px;
-  }
+In the event handler function, you can use the `event.stopPropagation()` 
method to prevent the event from escalating, which is exactly like the event's 
method with the same name in [DOM 
standard](https://dom.spec.whatwg.org/#dom-event-stoppropagation). Note that 
`event.stopPropagation()` differs from `bubble = "true"`, which affects only 
the current elements and the propagation of parent elements, without affecting 
the propagation of child elements; the latter is a switching mechanism that is 
added for compatibility, Will be a global shutdown or open the bubble 
mechanism, the two can co-exist.
 
-  .root {
-    font-size: 40px;
-    text-align: center;
-    background-color: #7a1b9b;
-    padding: 80px;
+```javascript
+{
+  handleClick (event) {
+    // stop event propagation.
+    event.stopPropagation()
   }
-</style>
+}
 ```
 
-[try it](http://dotwe.org/vue/2cc80e19c9b2430fb780234628065a69)
+## Notice
+
+One thing should be noticed: **For compatibility reason, Weex does not turn on 
event bubbling by default. You need to add `bubble = "true"` on the root 
element's properties to turn on the bubbling mechanism. Otherwise, Weex will 
keep working in the old way, without the event bubbling effect.**
+
+## Examples
+
+[enable event 
bubbling](http://dotwe.org/vue/fa2957ce3e9eb47ad9ae1da22d845e95): Use Weex 
playground APP to scan the qr-code, and then click on the middle of the 
rectangle with a line of text 'click me' on, you can see the event bubbling up, 
being handled with every listener binding on each div element, printing 
messages which indicate that they are indeed been reached by the event.
 
-Run the above code, open with the client, click on the middle of the element, 
you can see the event up to the parent element is terminated, no longer 
continue to spread to the root element.
+[stop event 
propagation](http://dotwe.org/vue/2cc80e19c9b2430fb780234628065a69): Use Weex 
playground APP to scan the qr-code, and then click on the middle of the 
rectangle with a line of text 'click me' on, you can see the event bubbling is 
disturbed, no longer continue to spread to the root element.

Reply via email to