数据绑定
Weex使用 mustache 的语法 ({{...}}) 来对 <template> 中的模板和 <script> 里的数据进行绑定. 一旦数据额模板绑定了, 数据上的修改会实时的在模板内容中生效。
样式: style 或 class
组件的样式能够通过style特性进行绑定:
<template>
<div>
<text style="font-size: {{size}}; color: {{color}};">Hello World</text>
</div>
</template>
<script>
module.exports = {
data: {
size: 32,
color: '#ff0000'
}
}
</script>
样式也能够通过class特性实现样式绑定,多个 class 名通过空格分隔:
<template>
<div>
<text class="{{size}}">Hello</text>
<text class="title {{status}}">World</text>
</div>
</template>
<style>
.large { font-size: 64; }
.small { font-size: 32; }
.title { font-weight: bold; }
.success { color: #00ff00; }
.error { color: #ff0000; }
</style>
<script>
module.exports = {
data: {
size: 'large',
status: 'success'
}
}
</script>
按下Ctrl+Shift+P调出命令面板输入install 调出 Install Package 选项并回车,然后在列表中选中要安装的插件。按下Ctrl+Shift+P调出命令面板输入install 调出 Install Package 选项并回车,然后在列表中选中要安装的插件。
weex hello.we
weex hello.we --qr
weex debug hello.we
在 Weex 中,您可以通过在特定的子组件上设置 id 特性,以此在该 <template> 内唯一标识这个组件。
Weex 代码由三部分构成:template、style、script,这三个概念之于 Weex 就如 HTML,CSS,JavaScript 之于 Web。
Weex 代码由 <template>、<style>、<script> 三个部分构成。
- <template>:必须的,使用 HTML 语法描述页面结构,内容由多个标签组成,不同的标签代表不同的组件。
- <style>:可选的,使用 CSS 语法描述页面的具体展现形式。
- <script>:可选的,使用 JavaScript 描述页面中的数据和页面的行为,Weex 中的数据定义也在 <script> 中进行。
每个 Weex 页面最顶层的节点,我们称为根节点。下面是目前我们支持的三种根节点:
- <div>:普通根节点,有确定的尺寸,不可滚动。
- <scroller>:可滚动根节点,适用于需要全页滚动的场景。
- <list>:列表根节点,适用于其中包含重复的子元素的列表场景。
目前 Weex 仅支持以上三种根节点。
<script> 描述页面中的数据和页面的行为,代码遵循 JavaScript (ES5) 语法 (目前 iOS 端和浏览器端取决于内置 JavaScript 引擎对 ES 版本的支持情况
上面 <script> 标签中定义了被赋值给 module.exports 的对象,这个对象其实就是一个 ViewModel 选项,
定义组件是通过一组选项来描述一个组件。这组选项总是被赋值给 <script> 标签中的 module.exports 。
module.exports = {
// a set of options here
}
data 选项是一个函数,它返回这个视图模型可监听的数据对象。而 methods 是一个映射,其中包含所有视图模型的方法。
每个 data 或 method 属性将被代理到视图模型实例中。所以,你能通过 this.x 读写数据,或者通过 this.doThis() 调用方法。
events 选项允许你在视图模型被创建时注册自定义事件。然后,它会监听这些类型的事件,并通过函数类型的值处理它们。
Weex 会把一个事件对象作为第一个参数传递给其绑定的事件,这个事件对象在 e.detail 中包含事件数据。
组件定义
定义组件是通过一组选项来描述一个组件。这组选项总是被赋值给 <script> 标签中的 module.exports
data 选项是一个函数,它返回这个视图模型可监听的数据对象。而 methods 是一个映射,其中包含所有视图模型的方法。
events 选项允许你在视图模型被创建时注册自定义事件。然后,它会监听这些类型的事件,并通过函数类型的值处理它们。
生命周期
module.exports = {
data: ...,
methods: ...,
init: function () {
console.log('ViewModel constructor begins')
console.log('在初始化内部变量,并且添加了事件功能后被触发');
},
created: function () {
console.log('Data observation finished')
console.log('完成数据绑定之后,模板编译之前被触发');
},
ready: function () {
console.log('Virtual DOM finished')
console.log('模板已经编译并且生成了 Virtual DOM 之后被触发');
},
destroyed: function () { console.log('在页面被销毁时调用'); },
...
}
Weex 视图模型现在支持生命周期内的钩子函数,这些钩子函数能被写为组件选项:
- init: 在视图模型的构造函数开始调用时激活;
- created: 当视图模型监听默认数据,但还未编译模板时激活;
- ready: 当视图模型监听默认数据并且编译模板生成虚拟DOM后被激活。
init内一般用于初始化一些内部变量,绑定一些自定义事件,这时还没有数据绑定,没有创建vdom,所以不能通过this获取到data和methods,也不能获取vdom的节点
created 完成了数据绑定 ,但还未开始编译模板,可以通过this获取data和methods,但不能获取vdom的节点
ready表示渲染完成 ,从子组件往上触发
destroyed 组件销毁,比如页面跳转,从子组件开始往上触发
注意:当 methods、events 或生命周期方法作为参数传递给别的函数时,务必确认函数执行时的上下文符合您的预期,例如:
module.exports = {
data: function () {
return {x: 1, y: 2}
},
ready: function () {
// `undefined`
// 因为上下文发生了变化
this.foo(this.bar)
// `1`
// 正确绑定上下文之后可以得到预期的值
this.foo(this.bar.bind(this))
},
methods: {
foo: function (fn) {
return fn()
},
bar: function () {
return this.x
}
}
}
Weex使用 mustache 的语法 ({{...}}) 来对 <template> 中的模板和 <script> 里的数据进行绑定. 一旦数据额模板绑定了, 数据上的修改会实时的在模板内容中生效。
注意事项:data、methods、computed 中的字段是不能相互重复的,因为它们都会通过组件实例的this 访问到。
事件绑定:on...
以 on... 开头的就是用于绑定事件的特性,特性名中 on 之后的部分就是事件的类型,特性的值就是处理该事件的函数名。函数名外不需要添加 mustache 语法中的大括号。
在 Weex 页面上样式有两种形式:
- <template> 中的 style 特性
- <style> 样式表
append
append 特性定义了当前组件的子组件:
- 以一整棵树的方式一次性添加到视图中 (append="tree"),还是
- 每个子组件都产生一次单独的添加到视图的指令 (append="node")
自定义组件
经常我们会发现 Weex 的 <template> 中有很多可复用的部分,这时候我们可以将其封装成上层的自定义组件并重用。例如我们可以直接创建一个名为 foo.we 的文件,<foo> 就是自定义组件的组件名称:
组件嵌套
自定义组件也支持嵌套,如下:
<!-- somepath/foo.we -->
<template>
<div style="flex-direction: row;">
<image src="{{image}}"></image>
<text>{{title}}</text>
</div>
</template>
<script>
module.exports = {
data: {
// These keys must be declared explicitly here
// or data-binding will not work from its parent.
title: null,
image: null
}
}
</script>
<!-- samepath/foo.list.we -->
<template>
<div>
<text>{{description}}</text>
<foo repeat="item in list" title="{{item.text}}" image="{{item.img}}"></foo>
</div>
</template>
<script>
module.exports = {
data: {
description: '',
// This key must be declared explicitly here
// or data-binding will not work from its parent.
list: []
}
}
</script>
<!-- samepath/main.we -->
<template>
<foo-list list="{{list}}"></foo-list>
</template>
<script>
module.exports = {
data: {
list: [
{text: '...', img: '...'},
{text: '...', img: '...'},
{text: '...', img: '...'},
...
]
}
}
</script>
这里的main.we嵌套了<foo-list>,<foo-list>嵌套了<foo>,同时组件可以正常的配合数据绑定、repeat特性等使用。
更多子组件的定义和书写方式
除了在主文件同目录下创建和被封装组件同名的 we 文件之外,Weex 还支持另外几种子组件的书写方式:
- 在 <script> 中通过 require 其它目录的 we 文件定义同名组件
- 在主文件下新增 <element name="xxx"> 标签,name 特性的值为新创建的组件名,其 <element> 内部的内容是定义该组件的代码
比如:
<!-- path-a/main.we -->
<element name="foo">
<text>Foo</text>
</element>
<template>
<div>
<foo></foo>
<bar></bar>
</div>
</template>
<script>
require('path-b/bar.we')
</script>
<!-- path-b/bar.we -->
<template>
<text>Bar</text>
</template>
这样的话,path-a/main.we 最终展示的结果是“Foo”和“Bar”两段文本。
注意事项
- 组件各自的 <style> 是相互独立的,不会担心不同组件中相同的 class name 相互干扰。
- 如果自定义组件在父组件中有 id 特性,则可以在父组件上下文中通过 this.$vm(id) 接口来访问该自定义组件的上下文,也可以通过 this.$el(id) 来找到其背后真实的原生组件。更多详见获取子组件信息
- 自定义组件之间通信的问题可以参考组件间通信
- 不论通过父组件把数据传递进来还是在当前组件内部对数据发起修改,只有在组件的 data 选项中明确写明的字段才会被正常的监听。
获取自定义子组件的上下文
另外,我们还可以通过this.$vm(id) 方法可以访问自定义子组件的上下文:
另外,我们还可以通过this.$vm(id)方法可以访问自定义子组件的上下文:
<element name="foo">
<template>
<div style="flex-direction: row;">
<text>{{title}}</text>
</div>
</template>
<script>
module.exports = {
data: {
title: null
},
methods: {
setTitle: function (text) {
this.title = text
}
}
}
</script>
</element>
<template>
<div>
<foo id="sub" title="Hello"></foo>
<text οnclick="update">Click Me to Update</text>
</div>
</template>
<script>
module.exports = {
methods: {
update: function (e) {
this.$vm('sub').setTitle('Updated')
}
}
}
</script>
获取子组件信息
在 Weex 中,您可以通过在特定的子组件上设置id特性,以此在该<template>内唯一标识这个组件。
获取子组件
您可以在父组件上下文中使用this.$el(id)来找到该组件,以运用scrollToElement()为例:
<template>
<div>
<text id="goto-top">Top</text>
<div style="height: 10000; "></div>
<text οnclick="back2Top">Back to Top</text>
</div>
</template>
<script>
var dom = require('@weex-module/dom')
module.exports = {
methods: {
back2Top: function () {
var el = this.$el('goto-top')
dom.scrollToElement(el, { offset: 10 })
}
}
}
</script>
组件间通信
自定义事件
Weex 支持自定义事件,这里有两个相关的设计:1,监听自定义事件;2,创建自定义事件。
监听自定义事件
每个 Weex 的 ViewModel 都支持 this.$on(type, handler) 和 this.$off(type[, handler]) 的 API。type 是监听的自定义事件类型,handler 是事件处理函数。
当 handler 被触发时,会有一个事件对象 event 作为第一个参数被传入,事件对象的数据格式基于事件机制中提到的事件描述对象。
创建自定义事件
每个 Weex 的 ViewModel 都支持 this.$emit(type, detail) 的 API,可以在当前 ViewModel 中产生一个自定义事件。type 是自定义事件的类型,detail 则是一个对该事件细节补充描述的 JSON 对象,会以 event.detail 的形式出现在处理此事件的函数中。
从子组件向父组件通信
首先父组件要监听特定类型的自定义事件,而子组件可以使用 this._parent 找到父组件,然后再调用 this._parent.$emit(type, detail) 方法,即可实现自下而上的通信。例如:
从父组件向子组件通信
同理,首先子组件要监听特定类型的自定义事件,而父组件可以使用 this.$vm(id) “访问自定义子组件的上下文”,然后再调用 this.$vm(id).$emit(type, detail) 方法,即可实现自上而下的通信。例如:
页面整体配置
在 Weex 中,你可以通过一些特殊的 <script> 进行页面整体配置。
注意事项:这些配置会代表页面整体,所以写在自定义子组件中是无效的,只有写在顶级 ViewModel 的 <sctipt> 中才会生效。
先举个例子:
<!-- definition of sub components -->
<element name="sub-component-a">...</element>
<element name="sub-component-b">...</element>
<element name="sub-component-c">...</element>
<!-- definition of top-level component -->
<template>...</template>
<style></style>
<script>
module.exports = {
data: { x: 1, y: 2 }
}
</script>
<!-- config and data -->
<script type="config">
downgrade: {
ios: {
os: '9', // all of 9.x.x
app: '~5.3.2',
framework: '^1.3', // all of 1.3.x
deviceModel: ['AAAA', 'BBBB']
},
android: {
os: '*', // all of version
app: '^5',
framework: '',
deviceModel: ''
}
}
</script>
<script type="data">
{ y: 200 }
</script>
<script type="config">
开发者可以在顶级 ViewModel 中加入这样一段 <script>,以 JSON 格式描述页面整体的配置信息。
目前支持的配置信息只有 downgrade:用来从平台、应用等维度描述页面的降级规则。这样设计对于产品迭代最大的帮助是可以在高版本中使用 Weex,而在低版本中使用之前已有的渲染方式,这部分控制降级的细节需要 native 接入的时候进行相应的识别和具体操作。
未来这里会有更多的配置项出现在这里。
<script type="data">
开发者可以在顶级 ViewModel 中加入这样一段 <script>,以 JSON 格式额外配置顶级 ViewModel 的数据,它会覆盖顶级 ViewModel 数据中相应的字段。比如上述例子中,最终的顶级 ViewModel 中的数据为 { x: 1, y: 200 }。