You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@weex.apache.org by ha...@apache.org on 2018/01/16 08:55:58 UTC
[1/4] incubator-weex-site git commit: * [doc] update the Weex
Variable documents
Repository: incubator-weex-site
Updated Branches:
refs/heads/master 1087b0548 -> 9ff27acfe
* [doc] update the Weex Variable documents
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/cdd6cbca
Tree: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/tree/cdd6cbca
Diff: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/diff/cdd6cbca
Branch: refs/heads/master
Commit: cdd6cbca0cb1c342360e7d3c110bf14af7dc2322
Parents: a4d6c39
Author: Hanks <zh...@gmail.com>
Authored: Tue Dec 26 15:47:23 2017 +0800
Committer: Hanks <zh...@gmail.com>
Committed: Tue Dec 26 15:47:23 2017 +0800
----------------------------------------------------------------------
source/cn/references/weex-variable.md | 147 ++++++++++++++++++++--------
source/references/weex-variable.md | 151 +++++++++++++++++++++--------
2 files changed, 214 insertions(+), 84 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/cdd6cbca/source/cn/references/weex-variable.md
----------------------------------------------------------------------
diff --git a/source/cn/references/weex-variable.md b/source/cn/references/weex-variable.md
index a6bdd11..198279e 100644
--- a/source/cn/references/weex-variable.md
+++ b/source/cn/references/weex-variable.md
@@ -4,39 +4,102 @@ type: references
group: API
order: 2.5
version: 2.1
-has_chapter_content: true
---
-# Weex 实例变量
+<!-- toc -->
-每个 Weex 页面的 JS 上下文中都有一个相互独立的 `weex` 变量，用来持有当前 Weex 页面相关的单例内容或方法。
+每个 Weex 页面的 JS 上下文中都有一个相互独立的 `weex` 变量，它可以像全局变量一样使用，不过它在不同页面中是隔离而且*只读*的。
+
+> **注意： `weex` 实例变量只在 Vue 框架中暴露了，目前还不支持在 Rax 框架中使用。**
+
+## 属性和方法
+
+Weex 实例变量的类型定义如下：
+
+```typescript
+declare type Weex = {
+ config: WeexConfigAPI;
+ document: WeexDocument;
+ requireModule: (name: string) => Object | void;
+ supports: (condition: string) => boolean | void;
+}
+```
## `weex.config`
-该变量包含了当前 Weex 页面的所有环境信息，包括不仅限于：
+该变量包含了当前 Weex 页面的所有环境信息。
+
+```typescript
+declare type WeexConfigAPI = {
+ bundleUrl: string;
+ bundleType?: string;
+ env: WeexEnvironment;
+}
+```
+
++ `bundleUrl`: 当前页面 js bundle 的 URL 地址。
++ `bundleType`: <span class="api-version">v0.17+</span> 页面 js bundle 的类型，它表示的是当前页面是用那种框架开发的，可以是 `"Vue"` 或者 `"Rax"`。
++ `env`: Weex 环境变量。
+
+### Weex 环境变量
+
+有时候为了兼容性或者为了增强某个端上的能力，需要编写平台特异的代码。 Weex 提供了 `weex.config.env` 和全局的 `WXEnvironment` 变量（它们是等价的）来获取当前执行环境的信息。
+
+```js
+weex.config.env === WXEnvironment
+```
+
+**Weex 环境变量中的字段**:
+
+| 字段名 | 类型 | 描述 |
+| -------------- | ------ | ----------- |
+| `platform` | String | Current running platform, could be "Android", "iOS" or "Web". |
+| `weexVersion` | String | The version of Weex SDK. |
+| `appName` | String | Mobile app name or browser name. |
+| `appVersion` | String | The version of current app. |
+| `osName` | String | The OS name, could be "Android" or "iOS". |
+| `osVersion` | String | The version of current OS. |
+| `deviceModel` | String | Mobile phone device model. (native only) |
+| `deviceWidth` | Number | Screen resolution width. |
+| `deviceHeight` | Number | Screen resolution height. |
+
+[这个例子](http://dotwe.org/vue/ea2cff9039f3b0e406f8f7da10e874af) 打印出了 Weex 环境对象中的所有值。
+
+## `weex.document`
+
+`weex.document` 是当前页面的文档模型对象，可以用来创建和操作 DOM 树中元素。它是 Weex DOM API 规范的一部分，但是它和 [W3C 的 DOM 规范](https://www.w3.org/DOM/)中的 `document` 对象是不同的。
+
+而且，在使用了现代化的前端框架（如 Vue 和 Rax）的情况下，直接操作 DOM 并不是最佳实践。更何况**在 Weex 平台里并不一定有真实的 DOM**，在 Android 和 iOS 端上都是模拟出来的。
+
+这个接口主要是用在 Vue 和 Rax 框架内部，用于将 virtual-dom 转换成渲染执行，并且发送给 Weex 客户端的渲染引擎。不建议在开发页面时使用。
+
+## `weex.requireModule`
-* `bundleUrl: string`: JS bundle 的 URL。
-* `env: Object`: 环境对象。
- * `weexVersion: string`: Weex sdk 版本。
- * `appName: string`: 应用名字。
- * `appVersion: string`: 应用版本。
- * `platform: string`: 平台信息，是 iOS、Android 还是 Web。
- * `osName: string`: iOS或者android，表示操作系统的名称.
- * `osVersion: string`: 系统版本。
- * `deviceModel: string`: 设备型号 (仅原生应用)。
- * `deviceWidth: number`: 设备宽度。Weex 默认以宽度为 750px 做适配渲染，要获得750px下的屏幕高度，可以通过 `height = 750/deviceWidth*deviceHeight` 公式获得，可以使用到 CSS 中，用来设置全屏尺寸
- * `deviceHeight: number`: 设备高度。
+对于那些不依赖 UI 交互的原生功能，Weex 将其封装成**模块**，这是一种通过 javascript 调用原生能力的方法。除了[内置模块](./modules/)以外，将已有的原生模块移植到 Weex 平台也很方便。你可以使用 `weex.requireModule` 接口引用自定义的或者内置的模块。
-## `weex.requireModule(module: string): Object`
+```typescript
+weex.requireModule(name: string): Object | void;
+```
+
+**参数：**
+
++ 大小写敏感的模块名。
+
+**返回值：**
+
++ 如果模块已经注册了，返回一个 `Proxy` 对象（如果环境不支持 `Proxy` 则返回一个普通对象），可以使用这个对象调用客户端注册的方法。
++ 如果模块未注册，返回 `undefined`。
+
+### 使用原生模块
-获取某个 native module 的所有方法，比如：
+你可以像使用不同 javascript 函数一样使用原生注册的接口。这里是一个简单的[使用 modal 模块的例子](http://dotwe.org/vue/cd7e97f7da08d6d4ca627fc127ab8828)：
```html
<template>
- <div><text>Hello World</text></div>
+ <div><text>Toast</text></div>
</template>
<script>
- var modal = weex.requireModule('modal')
+ const modal = weex.requireModule('modal')
modal.toast({
message: 'I am a toast.',
duration: 3
@@ -44,52 +107,54 @@ has_chapter_content: true
</script>
```
-## `weex.document: Document`
-
-返回当前 Weex 页面的文档对象。
-
## `weex.supports`
-<span class="weex-version">v0.15+</span>
-
-`weex.supports` 可以用来检测当前环境中是否支持某个特性。
+> 这个接口只在 <span class="api-version">v0.15+</span> 或以上的版本可用。
-> 目前仅在 Weex DSL 2.0 (.vue) 中支持。
+你应该了解 Weex 的组件和模块都是可以注册和配置的，这样导致了在不同环境中组件和模块的支持情况不一样。你可以使用 `weex.supports` 接口在运行期检测某个功能在当前环境中是否可用。
-### API
-
-```js
-weex.supports(condition : String) : Boolean | Null
+```typescript
+weex.supports(condition: string): boolean | void;
```
-#### 参数
+**参数：**
+ 特定格式的字符串：`@{type}/{name}`。
-`type` 必须是 "component" 或者 "module"。`name` 可以是标签名、模块名，也可以指定模块中的某个方法名（和模块名用 `.` 隔开）。
+`type` 必须是 `"component"` 和 `"module"` 之一。`name` 可以是标签名、模块名，也可以指定模块中的某个方法名（和模块名用 `.` 隔开）。
-#### 返回值
+**返回值：**
-+ 支持，则返回 `true`。
-+ 不支持，则返回 `false`。
++ 支持该特性，则返回 `true`。
++ 不支持该特性，则返回 `false`。
+ 参数格式错误或无法确定是否支持，则返回 `null`。
-### 例子
+### 使用范例
+
+检测某个组件是否可用：
```js
-// 检测是否支持某个组件
weex.supports('@component/slider') // true
weex.supports('@component/my-tab') // false
+```
+
+检测某个模块是否可用：
-// 检测是否支持某个模块
+```js
weex.supports('@module/stream') // true
weex.supports('@module/abcdef') // false
+```
-// 检测是否支持模块中的某个方法
+检测某个模块是否包含某个方法：
+
+```js
weex.supports('@module/dom.getComponentRect') // true
weex.supports('@module/navigator.jumpToPage') // false
+```
-// 无效的输入
+无效的输入：
+
+```js
weex.supports('div') // null
weex.supports('module/*') // null
weex.supports('@stream/fetch') // null
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/cdd6cbca/source/references/weex-variable.md
----------------------------------------------------------------------
diff --git a/source/references/weex-variable.md b/source/references/weex-variable.md
index be5ec14..0439179 100644
--- a/source/references/weex-variable.md
+++ b/source/references/weex-variable.md
@@ -6,36 +6,100 @@ order: 2.5
version: 2.1
---
-# Weex instance variable
+<!-- toc -->
-Each Weex page has a separate weex variable, which exists in the JS context. They hold a single instance or method of the current Weex page.
+Each page of Weex contains a `weex` variable in the js runtime context. It can be assessed directly just like a global object, but it's *readonly* and separated from different pages.
+
+> NOTE: **The `weex` variable only exposed in the Vue framework. It's not available in Rax framework yet.**
+
+## Properties and Methods
+
+The type declaration of the Weex variable is:
+
+```typescript
+declare type Weex = {
+ config: WeexConfigAPI;
+ document: WeexDocument;
+ requireModule: (name: string) => Object | void;
+ supports: (condition: string) => boolean | void;
+}
+```
## `weex.config`
-This variable contains all the environment information for the current Weex page, including not only:
+The `weex.config` contains all the environment information of current page.
+
+```typescript
+declare type WeexConfigAPI = {
+ bundleUrl: string;
+ bundleType?: string;
+ env: WeexEnvironment;
+}
+```
+
++ `bundleUrl`: The URL of the js bundle in current page.
++ `bundleType`: <span class="api-version">v0.17+</span> The type of the js bundle, it indicates which framework is using for current js bundle, could be `"Vue"` or `"Rax"`.
++ `env`: Weex environment object.
+
+### Weex Environment Object
+
+Sometimes, you still need to write some platform specific codes for compatibility or enhancement. Weex provides `weex.config.env` and a global object `WXEnvironment` (they are strictly equal) to get the information of current runtime environment.
+
+```js
+weex.config.env === WXEnvironment
+```
+
+**Properties in Weex environment object**:
+
+| Property | Type | Description |
+| -------------- | ------ | ----------- |
+| `platform` | String | Current running platform, could be "Android", "iOS" or "Web". |
+| `weexVersion` | String | The version of Weex SDK. |
+| `appName` | String | Mobile app name or browser name. |
+| `appVersion` | String | The version of current app. |
+| `osName` | String | The OS name, could be "Android" or "iOS". |
+| `osVersion` | String | The version of current OS. |
+| `deviceModel` | String | Mobile phone device model. (native only) |
+| `deviceWidth` | Number | Screen resolution width. |
+| `deviceHeight` | Number | Screen resolution height. |
+
+[This example](http://dotwe.org/vue/ea2cff9039f3b0e406f8f7da10e874af) prints all properties in the Weex environment object.
+
+## `weex.document`
-+ `BundleUrl`: string: The URL of the JS bundle.
-+ `Env: Object`: environment object.
-+ `WeexVersion: string`: Weex sdk version.
-+ `AppName: string`: application name.
-+ `AppVersion: string`: app version.
-+ `Platform: string`: platform information, that is iOS, Android or Web.
-+ `osName: string`: OS name information, that is iOS, Android.
-+ `OsVersion: string`: system version.
-+ `DeviceModel: string`: device model (native application only).
-+ `DeviceWidth: number`: device width
-+ `DeviceHeight: number`: device height. In Weex, the default width of viewport is 750px, thus you can obtain the height of screen by `height = 750/deviceWidth*deviceHeight` if the width of viewport remains its default value.
+The `weex.document` is the document object of current page, it can be used to create or manipulate the *Elements* in *DOM tree*. It's part of *Weex DOM API* specification which is NOT the same with the `document` object in the [W3C DOM API](https://www.w3.org/DOM/).
-`weex.requireModule(module: string): Object`
+However, it's not a good practice to manipulate DOM directly when using modern front-end frameworks, such as Vue and Rax. Especially, **there is no actually DOM in Weex**, it was simulated on the native (Android or iOS).
+
+This API is mainly used inside of the Vue and Rax framework to convert the virtual-dom into render directives and send them to native render engines of Weex. Not recommended for using it when developing pages.
+
+## `weex.requireModule`
+
+For those features which does not rely on the UI, Weex wraps them into **modules**. It is a way to access native capabilities in javascript. Except for the [built-in modules](./modules/), it's quite easy to integrate the existing native modules to Weex platform. After that, you can use `weex.requireModule` to require both customized and built-in modules.
+
+```typescript
+weex.requireModule(name: string): Object | void;
+```
-Get all the methods of a native module, such as:
+**Parameter:**
+
++ A case-sensitive module name.
+
+**Return Value:**
+
++ If the module is registered, return a `Proxy` or plain object if the context doesn't support `Proxy`. You can use it to call the registered methods in the module.
++ If the module is unregistered, return `undefined`.
+
+### Use Native Module
+
+You can require a native module and use its APIs just like normal javascript functions. Here is [a simple example](http://dotwe.org/vue/cd7e97f7da08d6d4ca627fc127ab8828) of using the [`modal`](../components/modal.html) module:
```html
<template>
- <div><text>Hello World</text></div>
+ <div><text>Toast</text></div>
</template>
<script>
- var modal = weex.requireModule('modal')
+ const modal = weex.requireModule('modal')
modal.toast({
message: 'I am a toast.',
duration: 3
@@ -43,53 +107,54 @@ Get all the methods of a native module, such as:
</script>
```
-
-## `weex.document: Document`
-
-Returns the document object of the current Weex page.
-
## `weex.supports`
-<span class="weex-version">v0.15+</span>
-
-`weex.supports` is a method used to detect whether a feature is supported in the current environment.
+> This API only available in <span class="api-version">v0.15+</span>.
-> Only supported in Weex DSL 2.0 (.vue).
+As you may know, components and modules are extendable and configurable in Weex. So it could be various in different apps or running context. You can use `weex.supports` to detect whether a feature is supported in the current environment at runtime.
-### API
-
-```js
-weex.supports(condition : String) : Boolean | Null
+```typescript
+weex.supports(condition: string): boolean | void;
```
-#### Parameter
+**Parameter:**
-+ a formatted string: `@{type}/{name}`.
++ A formatted condition string: `@{type}/{name}`.
-The `type` must be "component" or "module", the `name` can be tag name, module name or the method name in specific module.
+The `type` must be `"component"` or `"module"`. The `name` could be a tag name, module name or the method name in specific module.
-#### Return Value
+**Return Value:**
-+ if supported, returns `true`.
-+ if unsupported, returns `false`.
-+ if unclear, returns `null`.
++ If the feature is supported, return `true`.
++ If the feature is unsupported, return `false`.
++ If not sure about whether this feature is supported, return `null`.
-### Example
+### Examples
+
+Detects whether the specific component is supported:
```js
-// Detects whether the specific component is supported
weex.supports('@component/slider') // true
weex.supports('@component/my-tab') // false
+```
+
+Detects whether the specific module is supported:
-// Detects whether the specific module is supported
+```js
weex.supports('@module/stream') // true
weex.supports('@module/abcdef') // false
+```
-// Detects whether the method in specific module is supported
+Detects whether the method in specific module is supported:
+
+```js
weex.supports('@module/dom.getComponentRect') // true
weex.supports('@module/navigator.jumpToPage') // false
+```
-// invalid input
+Invalid input or unknown features:
+
+```js
weex.supports('div') // null
weex.supports('module/*') // null
weex.supports('@stream/fetch') // null
[4/4] incubator-weex-site git commit: [doc] add documents for
BroadcastChannel (#21)
Posted by ha...@apache.org.
[doc] add documents for BroadcastChannel (#21)
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/9ff27acf
Tree: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/tree/9ff27acf
Diff: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/diff/9ff27acf
Branch: refs/heads/master
Commit: 9ff27acfe14597fe5a4fda895fe98dc5259786f5
Parents: 432d540 e2d2f8f
Author: Hanks <zh...@gmail.com>
Authored: Tue Jan 16 16:55:24 2018 +0800
Committer: Hanks <zh...@gmail.com>
Committed: Tue Jan 16 16:55:24 2018 +0800
----------------------------------------------------------------------
source/cn/references/broadcast-channel.md | 113 +++++++++++++++++++++
source/cn/references/js-framework-apis.md | 67 ------------
source/references/broadcast-channel.md | 113 +++++++++++++++++++++
source/references/images/BroadcastChannel.png | Bin 0 -> 50463 bytes
source/references/js_framework-apis.md | 67 ------------
5 files changed, 226 insertions(+), 134 deletions(-)
----------------------------------------------------------------------
[3/4] incubator-weex-site git commit: [doc] update the "Weex
Variable" documents (#20)
Posted by ha...@apache.org.
[doc] update the "Weex Variable" documents (#20)
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/432d5407
Tree: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/tree/432d5407
Diff: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/diff/432d5407
Branch: refs/heads/master
Commit: 432d540738afa1a10ccb3c6b769e071a46f8f22d
Parents: 1087b05 cdd6cbc
Author: Hanks <zh...@gmail.com>
Authored: Tue Jan 16 16:54:36 2018 +0800
Committer: Hanks <zh...@gmail.com>
Committed: Tue Jan 16 16:54:36 2018 +0800
----------------------------------------------------------------------
source/cn/references/weex-variable.md | 147 ++++++++++++++++++++--------
source/references/weex-variable.md | 151 +++++++++++++++++++++--------
2 files changed, 214 insertions(+), 84 deletions(-)
----------------------------------------------------------------------
[2/4] incubator-weex-site git commit: + [doc] add documents for
BroadcastChannel
Posted by ha...@apache.org.
+ [doc] add documents for BroadcastChannel
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/e2d2f8f4
Tree: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/tree/e2d2f8f4
Diff: http://git-wip-us.apache.org/repos/asf/incubator-weex-site/diff/e2d2f8f4
Branch: refs/heads/master
Commit: e2d2f8f42de8f07c2e377ba1b63d961f5e10afca
Parents: a4d6c39
Author: Hanks <zh...@gmail.com>
Authored: Tue Dec 26 20:35:04 2017 +0800
Committer: Hanks <zh...@gmail.com>
Committed: Tue Dec 26 20:41:59 2017 +0800
----------------------------------------------------------------------
source/cn/references/broadcast-channel.md | 113 +++++++++++++++++++++
source/cn/references/js-framework-apis.md | 67 ------------
source/references/broadcast-channel.md | 113 +++++++++++++++++++++
source/references/images/BroadcastChannel.png | Bin 0 -> 50463 bytes
source/references/js_framework-apis.md | 67 ------------
5 files changed, 226 insertions(+), 134 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/e2d2f8f4/source/cn/references/broadcast-channel.md
----------------------------------------------------------------------
diff --git a/source/cn/references/broadcast-channel.md b/source/cn/references/broadcast-channel.md
new file mode 100644
index 0000000..d626a85
--- /dev/null
+++ b/source/cn/references/broadcast-channel.md
@@ -0,0 +1,113 @@
+---
+title: BroadcastChannel
+type: references
+group: API
+order: 2.8
+version: 2.1
+---
+
+<!-- toc -->
+
+> `BroadcastChannel` 接口在 <span class="api-version">v0.9+</span> 及以上的版本中可用。
+
+在 [JS 执行环境](./runtime-context.html)中提到过，不同的 Weex 页面使用的是不同的执行环境，即使全局变量也是互相隔离的，然而使用 `BroadcastChannel` 是可以实现跨页面通信的。
+
+## API
+
+> *BroadcastChannel* 是 [W3C 规范](https://html.spec.whatwg.org/multipage/comms.html#broadcasting-to-other-browsing-contexts)中的一部分，其中依赖的 [MessageEvent](https://html.spec.whatwg.org/multipage/comms.html#messageevent) 对象也是。
+
+`BroadcastChannel` 的构造函数只接受一个参数，那就是“频道名称”（channel name）。
+
+```js
+const jb = new BroadcastChannel('007')
+```
+
+`BroadcastChannel` 接口的定义如下：
+
+```typescript
+declare interface BroadcastChannel = {
+ name: string,
+ postMessage: (message: any) => void;
+ onmessage: (event: MessageEvent) => void;
+ close: () => void;
+}
+```
+
++ `name`: 监听的频道名称，用来区分不同的频道（跨频道不可通信）。
++ `postMessage`: 用于在当前频道中广播消息。
++ `onmessage`: 消息事件的处理函数。在频道中接收到广播消息之后，会给所有订阅者派发消息事件。
++ `close`: 关闭当前频道。
+
+消息对象（`MessageEvent`）的类型定义如下：
+
+```typescript
+declare interface MessageEvent = {
+ type: string, // "message"
+ data: any
+}
+```
+
+## 通信过程
+
+
+
+就像使用无线电一样，每个页面通过创建一个具有相同频道名称的 BroadcastChannel 对象来加入特定频道。 然后实现 `onmessage` 接口来监听消息事件。通过调用 BroadcastChannel 对象上的 `postMessage()` 方法可以在频道中广播一条消息给所有订阅者。
+
+事实上，这是在特定频道的所有用户之间的全双工（双向）通信，每个订阅者都可以在频道中彼此收发任何消息，即使消息的发送者也能收到自己发出的消息事件。不同频道之间的通信过程是不会互相影响的。
+
+调用 BroadcastChannel 对象的 `close()` 方法可以离开一个频道，这个方法只关闭自己，并不影响其他订阅者。当某个 Weex 页面被销毁时，其中的所有订阅者将在 `destroyInstance` 中强制关闭。如果某个频道的所有用户都关闭了，这个频道对象将会被销毁，所占内存页能被回收。
+
+## 使用范例
+
+在页面 A 中：
+
+```js
+const Steve = new BroadcastChannel('Avengers')
+Steve.postMessage('Assemble!')
+```
+
+在页面 B 中：
+
+```js
+const Hulk = new BroadcastChannel('Avengers')
+```
+
+在页面 C 中：
+
+```js
+const Stack = new BroadcastChannel('Avengers')
+Stack.onmessage = function (event) {
+ console.log(event.data) // Assemble!
+ Stack.postMessage('I am Tony and I am leaving now.')
+}
+```
+
+页面 A 、B 、C 都创建一个监听了 `'Avengers'` 频道的 BroadcastChannel 对象，它们可以用这个对象实现互相通信。
+
+当 Steve 发布了 `'Assemble!'` 消息时，Stack 将收到一个消息事件，其 `data` 字段等于 `'Assemble!'`，然后也向频道中回复一条消息。但是 Hulk 并不会收到这些消息，因为他没有实现`onmessage` 方法，相当于没有接收频道中的消息，所以他实际上不是一个订阅者。
+
+## 注意事项
+
+> **消息事件中的对象并没有深度复制。**（这个特性可能会修改）
+
+在页面 A 中：
+
+```js
+const a = new BroadcastChannel('app')
+const list = ['A', 'B']
+a.postMessage({ list })
+```
+
+在页面 B 中：
+
+```js
+const b = new BroadcastChannel('app')
+b.onmessage = function (event) {
+ // the `event.data.list` is a reference of `list` in page A
+ event.data.list.push('C')
+}
+```
+
+在这个例子中，页面 B 中的 `event.data.list` 实际上是页面 A 中 `list` 对象的引用。在页面 B 中给列表添加一项 `'C'`，也将影响到页面 A 中的 `list` 对象。
+
+相比于深度复制，这个行为可以减少页面中的内存消耗。开发者在使用时不应该存储或修改 `event` 对象。
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/e2d2f8f4/source/cn/references/js-framework-apis.md
----------------------------------------------------------------------
diff --git a/source/cn/references/js-framework-apis.md b/source/cn/references/js-framework-apis.md
deleted file mode 100644
index 2aafd5e..0000000
--- a/source/cn/references/js-framework-apis.md
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: JS Framework APIs
-type: references
-group: API
-order: 2.4
-version: 2.1
----
-
-# JS Framework APIs
-
-## BroadcastChannel <span class="api-version">v0.9+</span>
-
-`BroadcastChannel` API 是 Weex 实例间通信的解决方案。
-
-### 参考
-
-+ [BroadcastChannel specification](https://html.spec.whatwg.org/multipage/comms.html#broadcasting-to-other-browsing-contexts).
-+ [MessageEvent specification](https://html.spec.whatwg.org/multipage/comms.html#messageevent)
-
-### API
-
-+ `postMessage(message)`: 通过消息通道发送特定消息给其他 BroadcastChannel 对象。
-+ `close`: 关闭 BroadcastChannel 对象，以便垃圾回收。
-+ `onmessage`: Event 处理函数, 当 BroadcastChannel 对象接收到消息时触发。
-
-### 使用
-
-```javascript
-const Stack = new BroadcastChannel('Avengers')
-Stack.onmessage = function (event) {
- console.log(event.data) // in this case, it's "Hulk Smash !!!"
-}
-
-// in another instance
-const Hulk = new BroadcastChannel('Avengers')
-Hulk.postMessage("Hulk Smash !!!")
-```
-
-运行以上代码，Stack 可以从 Hulk 接收消息。
-
-### 注意
-
-需要注意的是: ** `message` 如果是一个对象，该对象不会深拷贝。**
-
-参考以下例子
-
-```javascript
-const a = new BroadcastChannel('app')
-const b = new BroadcastChannel('app')
-
-const message = {
- lists: ['A', 'B']
-}
-
-a.onmessage = function (event) {
-
- // in this case, event.data is a reference of message
- console.assert(event.data === message)
-
-}
-
-b.postMessage(message)
-```
-
-在这个例子中，`event.data` 全等于 `message`。
-
-与深拷贝相比，这种方式能够提高效率并减少内存消耗。但是，不建议开发者在使用时缓存或修改事件对象 (所有类型的事件处理程序都应该有此限制)。
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/e2d2f8f4/source/references/broadcast-channel.md
----------------------------------------------------------------------
diff --git a/source/references/broadcast-channel.md b/source/references/broadcast-channel.md
new file mode 100644
index 0000000..e6069a6
--- /dev/null
+++ b/source/references/broadcast-channel.md
@@ -0,0 +1,113 @@
+---
+title: BroadcastChannel
+type: references
+group: API
+order: 2.8
+version: 2.1
+---
+
+<!-- toc -->
+
+> The `BroadcastChannel` is available since <span class="api-version">v0.9+</span>.
+
+As mentioned in [JS Runtime Context](./runtime-context.html), Weex is using different context for each page, even global variables are isolated, but `BroadcastChannel` is a way to achieve cross-page communication.
+
+## API
+
+> *BroadcastChannel* is part of [W3C specifications](https://html.spec.whatwg.org/multipage/comms.html#broadcasting-to-other-browsing-contexts), as well as the [MessageEvent](https://html.spec.whatwg.org/multipage/comms.html#messageevent).
+
+The constructor of `BroadcastChannel` only take one single parameter which is the channel name.
+
+```js
+const jb = new BroadcastChannel('007')
+```
+
+The type declaration of the `BroadcastChannel` is:
+
+```typescript
+declare interface BroadcastChannel = {
+ name: string,
+ postMessage: (message: any) => void;
+ onmessage: (event: MessageEvent) => void;
+ close: () => void;
+}
+```
+
++ `name`: The channel name, it's the indicator when broadcast messages.
++ `postMessage`: Sends the given message to other BroadcastChannel objects set up for this channel.
++ `onmessage`: The event handler. An event will be triggered when the instance received a message.
++ `close`: Closes the BroadcastChannel object, opening it up to garbage collection.
+
+The type declaration of the `MessageEvent` is:
+
+```typescript
+declare interface MessageEvent = {
+ type: string, // "message"
+ data: any
+}
+```
+
+## Communication Procedure
+
+
+
+Just like using radio, each client joins a specific channel by creating a `BroadcastChannel` object with the same channel name. Then implement the `onmessage` event handler to listen on the underlying channel. Call the `postMessage()` method on the BroadcastChannel object will broadcast a message to every subscriber of the channel.
+
+Indeed, it's a full-duplex (bi-directional) communication between all subscriber of the particular channel, each of them is able to receive any message that has been posted to it. Even the sender of the message can receive the message event itself. Communications between different channels will not affect each other.
+
+To leave a channel, it is required to call the `close()` method on the BroadcastChannel object. This method only closed itself, and does not affect other subscribers. When a Weex page is destroyed, all subscribers in it will be closed at `destroyInstance`. If all subscribers of a channel are closed, the underlying channel would be destroyed and allows garbage collection to happen.
+
+## Usage Example
+
+In page A:
+
+```js
+const Steve = new BroadcastChannel('Avengers')
+Steve.postMessage('Assemble!')
+```
+
+In page B:
+
+```js
+const Hulk = new BroadcastChannel('Avengers')
+```
+
+In page C:
+
+```js
+const Stack = new BroadcastChannel('Avengers')
+Stack.onmessage = function (event) {
+ console.log(event.data) // Assemble!
+ Stack.postMessage('I am Tony and I am leaving now.')
+}
+```
+
+The page A, B and C are all create a BroadcastChannel object which is listening on the `'Avengers'` channel. They can use it to communicate with each other.
+
+When Steve post the message `'Assemble!'`, Stack will receive a message event whose `data` equals the `'Assemble!'`, and then send another message back. But Hulk will not receive the message because he does not implement the `onmessage` method, so he is not a subscriber actually.
+
+## Notice
+
+> **The `message` object is not deep cloned.** (This feature could be changed.)
+
+In page A:
+
+```js
+const a = new BroadcastChannel('app')
+const list = ['A', 'B']
+a.postMessage(list)
+```
+
+In page B:
+
+```js
+const b = new BroadcastChannel('app')
+b.onmessage = function (event) {
+ // the event.data is a reference of list in page A
+ event.data.push('C')
+}
+```
+
+In this case, the `event.data` in page B is a reference of `list` in page A. When pushing a new item `'C'`, it will also affect the `list` object in page A.
+
+Compared to the deep clone, this behavior improves efficiency and reduces memory cost. However, developers are not recommended caching or modifying the `event` object after received it.
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/e2d2f8f4/source/references/images/BroadcastChannel.png
----------------------------------------------------------------------
diff --git a/source/references/images/BroadcastChannel.png b/source/references/images/BroadcastChannel.png
new file mode 100644
index 0000000..050e043
Binary files /dev/null and b/source/references/images/BroadcastChannel.png differ
http://git-wip-us.apache.org/repos/asf/incubator-weex-site/blob/e2d2f8f4/source/references/js_framework-apis.md
----------------------------------------------------------------------
diff --git a/source/references/js_framework-apis.md b/source/references/js_framework-apis.md
deleted file mode 100644
index 4f5a129..0000000
--- a/source/references/js_framework-apis.md
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: JS Framework APIs
-type: references
-group: API
-order: 2.4
-version: 2.1
----
-
-# JS Framework APIs
-
-## BroadcastChannel <span class="api-version">v0.9+</span>
-
-`BroadcastChannel` API is the solution for inter-instance communication.
-
-### Reference
-
-+ [BroadcastChannel specification](https://html.spec.whatwg.org/multipage/comms.html#broadcasting-to-other-browsing-contexts).
-+ [MessageEvent specification](https://html.spec.whatwg.org/multipage/comms.html#messageevent)
-
-### API
-
-+ `postMessage(message)`: Sends the given message to other BroadcastChannel objects set up for this channel.
-+ `close`: Closes the BroadcastChannel object, opening it up to garbage collection.
-+ `onmessage`: Event handler, the event will be triggered when the instance receive a message.
-
-### Usage
-
-```javascript
-const Stack = new BroadcastChannel('Avengers')
-Stack.onmessage = function (event) {
- console.log(event.data) // in this case, it's "Hulk Smash !!!"
-}
-
-// in another instance
-const Hulk = new BroadcastChannel('Avengers')
-Hulk.postMessage("Hulk Smash !!!")
-```
-
-Run the code above, Stack can receive the message from Hulk.
-
-### Notice
-
-One thing should be noticed: **The `message` object is not deep cloned.**
-
-See the demo below:
-
-```javascript
-const a = new BroadcastChannel('app')
-const b = new BroadcastChannel('app')
-
-const message = {
- lists: ['A', 'B']
-}
-
-a.onmessage = function (event) {
-
- // in this case, event.data is a reference of message
- console.assert(event.data === message)
-
-}
-
-b.postMessage(message)
-```
-
-In this case, `event.data` is strict equal to `message`.
-
-Compared to the deep clone, this behavior improves efficiency and reduces memory cost. However, developers are not recommended to cache or modify the `event` object when they are using it (All type of event handlers should have this restriction).