每个 Weex 页面的 JS 上下文中都有一个相互独立的 weex 变量,它可以像全局变量一样使用,不过它在不同页面中是隔离而且只读的。

注意: weex 实例变量只在 Vue 框架中暴露了,目前还不支持在 Rax 框架中使用。

属性和方法

Weex 实例变量的类型定义如下:

  1. declare type Weex = {
  2. config: WeexConfigAPI;
  3. document: WeexDocument;
  4. requireModule: (name: string) => Object | void;
  5. supports: (condition: string) => boolean | void;
  6. }

config

该变量包含了当前 Weex 页面的所有环境信息。

  1. declare type WeexConfigAPI = {
  2. bundleUrl: string;
  3. bundleType?: string;
  4. env: WeexEnvironment;
  5. }
  • bundleUrl: 当前页面 js bundle 的 URL 地址。
  • bundleType: v0.17+ 页面 js bundle 的类型,它表示的是当前页面是用那种框架开发的,可以是 "Vue" 或者 "Rax"
  • env: Weex 环境变量。

Weex 环境变量

有时候为了兼容性或者为了增强某个端上的能力,需要编写平台特异的代码。 Weex 提供了 weex.config.env 和全局的 WXEnvironment 变量(它们是等价的)来获取当前执行环境的信息。

  1. 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.

这个例子 打印出了 Weex 环境对象中的所有值。

document

weex.document 是当前页面的文档模型对象,可以用来创建和操作 DOM 树中元素。它是 Weex DOM API 规范的一部分,但是它和 W3C 的 DOM 规范中的 document 对象是不同的。

而且,在使用了现代化的前端框架(如 Vue 和 Rax)的情况下,直接操作 DOM 并不是最佳实践。更何况在 Weex 平台里并不一定有真实的 DOM,在 Android 和 iOS 端上都是模拟出来的。

这个接口主要是用在 Vue 和 Rax 框架内部,用于将 virtual-dom 转换成渲染执行,并且发送给 Weex 客户端的渲染引擎。不建议在开发页面时使用。

requireModule

对于那些不依赖 UI 交互的原生功能,Weex 将其封装成模块,这是一种通过 javascript 调用原生能力的方法。除了内置模块以外,将已有的原生模块移植到 Weex 平台也很方便。你可以使用 weex.requireModule 接口引用自定义的或者内置的模块。

  1. weex.requireModule(name: string): Object | void;

参数:

  • 大小写敏感的模块名。

返回值:

  • 如果模块已经注册了,返回一个 Proxy 对象(如果环境不支持 Proxy 则返回一个普通对象),可以使用这个对象调用客户端注册的方法。
  • 如果模块未注册,返回 undefined

使用原生模块

你可以像使用不同 javascript 函数一样使用原生注册的接口。这里是一个简单的使用 modal 模块的例子

  1. <template>
  2. <div><text>Toast</text></div>
  3. </template>
  4. <script>
  5. const modal = weex.requireModule('modal')
  6. modal.toast({
  7. message: 'I am a toast.',
  8. duration: 3
  9. })
  10. </script>

supports

这个接口只在 v0.15+ 或以上的版本可用。

你应该了解 Weex 的组件和模块都是可以注册和配置的,这样导致了在不同环境中组件和模块的支持情况不一样。你可以使用 weex.supports 接口在运行期检测某个功能在当前环境中是否可用。

  1. weex.supports(condition: string): boolean | void;

参数:

  • 特定格式的字符串:@{type}/{name}

type 必须是 "component""module" 之一。name 可以是标签名、模块名,也可以指定模块中的某个方法名(和模块名用 . 隔开)。

返回值:

  • 支持该特性,则返回 true
  • 不支持该特性,则返回 false
  • 参数格式错误或无法确定是否支持,则返回 null

使用范例

检测某个组件是否可用:

  1. weex.supports('@component/slider') // true
  2. weex.supports('@component/my-tab') // false

检测某个模块是否可用:

  1. weex.supports('@module/stream') // true
  2. weex.supports('@module/abcdef') // false

检测某个模块是否包含某个方法:

  1. weex.supports('@module/dom.getComponentRect') // true
  2. weex.supports('@module/navigator.jumpToPage') // false

无效的输入:

  1. weex.supports('div') // null
  2. weex.supports('module/*') // null
  3. weex.supports('@stream/fetch') // null
  4. weex.supports('getComponentRect') // null

isRegisteredModule

检测某个特定的模块或者接口是否可用。

  1. weex.isRegisteredModule(moduleName: string, methodName: string): boolean

这个接口只能用于检测特定模块和方法的兼容性,不支持检测组件。

  1. weex.isRegisteredModule('stream') // true
  2. weex.isRegisteredModule('stream', 'fetch') // true
  3. weex.isRegisteredModule('whatever', '- unknown -') // false
  4. weex.isRegisteredModule('div') // false, not support components

isRegisteredComponent

检测某个特定的组件是否可用。

  1. weex.isRegisteredComponent(componentName: string): boolean

这个接口只能用于检测组件的兼容性,不支持检测模块。

  1. weex.isRegisteredComponent('div') // true
  2. weex.isRegisteredComponent('- unknown -') // false
  3. weex.isRegisteredComponent('navigator') // false, not support modules