# 在 Weex 中使用 Rax.js

TIP

Rax 是一个兼容 React 接口的前端框架，请访问 Rax 的官方网站 (opens new window) 了解更多信息。

什么是 Rax

如果你习惯于 React 的书写方式，欢迎使用 Rax，Rax 是一款超轻量，高性能，易上手的前端解决方案。一次开发多端运行，同时支持 Weex Web 小程序等不同端。

# 环境变量

Weex 提供 WXEnvironment 用来获取 Weex 运行的环境变量，Rax 页面可以通过 WXEnvironment 访问。提供字段如下：

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.

Rax 环境中的全局变量 Weex 在 WeexSDK 0.15 版本之后提供

# Weex Rax Framework

Native 和 Web 天生就有很多差异，为了让开发者有更好的体验，大部分的差异是不需要让开发者去关心的。因此 Native 端通过 Framework 模拟出了大量 Web 端的标准全局 API。

常用 API 包括

W3C API
name	closed	atob	btoa	performance
document	location	navigator	screen	devicePixelRatio
fetch	setTimeout	clearTimeout	setInterval	clearInterval
requestAnimationFrame	cancelAnimationFrame	alert	open	close
postMessage	addEventListener	removeEventListener	dispatchEvent	onerror
Promise	Symbol	Map	Set	WeakMap
WeakSet	Headers	Response	Request	XMLHttpRequest
URL	URLSearchParams	FontFace	WebSocket	Event
CustomEvent	matchMedia

其中部分实现依赖 Weex Module 能力

fetch 使用 @weex-module/stream
setTimeout 使用 @weex-module/timer
clearTimeout 使用 @weex-module/timer
setInterval 使用 @weex-module/timer
clearInterval 使用 @weex-module/timer
requestAnimationFrame 使用 @weex-module/timer
cancelAnimationFrame 使用 @weex-module/timer
alert 使用 @weex-module/modal
open 使用 @weex-module/navigator
close 使用 @weex-module/navigator
postMessage 使用 BroadcastChannel 能力
addEventListener 跨页面监听使用 BroadcastChannel 能力，页面内监听使用内部的 Emitter
onerror 使用 @weex-module/globalEvent

模块规范

API	描述
define	组件定义
require	组件依赖，支持 Rax 组件与 Weex 原生模块，注意 Weex 模块需要以 @weex-module/ 开头

其他 API

API	描述
`__weex_document__`	createInstanceContext 过程中创建的 Document 实例
`__weex_module_supports__`	weex.isRegisteredModule
`__weex_tag_supports__`	weex.isRegisteredComponent
`__weex_define__`	组件定义
`__weex_require__`	组件依赖，支持 Rax 组件与 Weex 原生模块，注意 Weex 模块需要以
`__weex_downgrade__`	页面降级方法，依赖 @weex-module/instanceWrap
`__weex_env__`	WXEnvironment
`__weex_options__`	创建 Instance 所传递的参数
`__weex_data__`	创建 Instance 所传递的数据
`__weex_config__`	同 weex_options

# 样式支持

Rax 样式在 Weex 端与 Weex 所提供能力相同，并无额外扩展样式。

# 使用组件

Rax 的基础组件内部实现抹平了各端的差异，在 Weex 端的实现是Weex 提供的基础组件。例如 rax-view 的实现是 div，rax-text 的实现是 text。

Rax 基础组件会将所有属性向下透传，并对核心逻辑进行多端的兼容。示例：

<list loadmoreoffset={...}>
	...
</list>

1
2
3

Weex 组件与 Rax 混用

<View>
  <text>Hello Rax</text>
</View>

1
2
3

# 使用 Weex 模块

Rax 提供了多端兼容的 API universal-api (opens new window)。但在某些特殊场景下，如果向自己引用原生模块的方法，可以按照如下方式使用

以 Weex Dom 模块为例

let dom = require('@weex-module/dom');
dom.scrollToElement(someNode, {
  offset: 20,
});

1
2
3
4

或

let dom = __weex_require__('@weex-module/dom');
dom.scrollToElement(someNode, {
  offset: 20,
});

1
2
3
4

# 页面降级

Rax 页面降级可以使用 Weex Module @weex-module/instanceWrap，也可以使用更方便的辅助工具 @weex-project/downgrade

Rax Framework 中也提供了全局的降级方法 __weex_downgrade__ 方便开发者使用

# 事件

组件通用事件与 Weex 通用事件相同，Rax 中需要以 on 开头驼峰方式命名

<View onClick={() => {}}>
  ...
</View>

1
2
3

页面事件，需要通过 setNativeProps API 手动向 body 节点绑定

let bodyProps = {
  onViewAppear: () => {},
  onViewDisAppear: () => {}
};
let weexDocument = typeof __weex_document__ === 'object' ? __weex_document__ : typeof document === 'object' ? document : {};
if (weexDocument && weexDocument.body) {
  setNativeProps(findDOMNode(weexDocument.body), bodyProps);
}

1
2
3
4
5
6
7
8

事件冒泡

let bodyProps = {
  bubble: true,
};
let weexDocument = typeof __weex_document__ === 'object' ? __weex_document__ : typeof document === 'object' ? document : {};
if (weexDocument && weexDocument.body) {
  setNativeProps(findDOMNode(weexDocument.body), bodyProps);
}

1
2
3
4
5
6
7

阻止冒泡

<View onClick={(event) => {
	event.stopPropagation();
}}>
  ...
</View>

1
2
3
4
5

# 事件通信

Weex 提供了页面间通信的能力 BroadcastChannel（weex v0.9+）, Rax 页面中可以通过 Window 的全局方法进行通信。

# 页面间通信

页面 A 发送消息

window.postMessage('{hello:1}',  '*');

页面 B 接收消息

window.addEventListener('message', (e) => {
  console.log('data is', e.data);
});

1
2
3

# 页面内消息广播

页面内发送消息

window.dispatchEvent(new CustomEvent('eventName', { detail: 1 }));

页面内接收消息

window.addEventListener('eventName', (event) => {
	const {detail} = event;
	// 业务逻辑
});

1
2
3
4

← Playground 应用在 Weex 中使用 Vue.js →