WXML(WeiXin Markup Language)是框架设计的一套标签语言,结合基础组件、事件系统,可以构建出页面的结构。
WXML 中的动态数据均来自对应 Page 的 data。
数据绑定使用 Mustache 语法(双大括号)将变量包起来,可以作用于:
内容
//.wxml文件
{{ message }}
//.js文件
Page({
data: {
message: 'Hello MINA!'
}
})
简单绑定我们在这之前就学过了,在这我们就不详细做实验了
这个组件属性是指, page中data的数据可以作用于组件中, 比如;
xxx.wxml文件
xxx.js文件
Page({
data: {
id: 0
}
})
逻辑层经过视图层渲染后,
我们把上述代码运行一下, 然后查看网页结构, 在开发者工具的wxml处, 显示如下:
和我们分析的一摸一样。
控制属性是指page下data的数据可以作用于控制语句(if, for 等等)
我们做一个小实验, 在page data下定义一个condition变量, 如果该变量为真, 在页面显示data下的text_true信息, 如果为假, 显示data下的text_false信息
.js文件代码:
Page({
/**
* 页面的初始数据
*/
data: {
text_true :"condition is true",
text_false: "condition is false",
condition: false
}
})
.wxml文件代码:
{{text_true}}
{{text_false}}
运行:
改变 condition为true 运行:
效果和预期一样
true
:boolean 类型的 true,代表真值。
false
: boolean 类型的 false,代表假值。
特别注意:不要直接写 checked="false"
,其计算结果是一个字符串,转成 boolean 类型后代表真值。
其实看到这, 我们似乎明白了其实上面那种情况和这种情况类似, 只是上面那种情况在这的基础上进行了转化,把condition的转变为true或者false而已
可以在 {{}}
内进行简单的运算,支持的有如下几种方式:
5.1三元运算
{{status % 2==1?"微信小程序":"支付宝小程序"}}
这里的三目运算符和其他语言的三目运算符类似, a ? b : c 当a为真时, 运行b处的语句, a为假时, 运行c处的语句。 像上面那个例子, 表示, 当status为奇数时view标签显示微信小程序, status为偶数时显示支付宝小程序
5.2 算数运算
{{a + b}} + {{c}} + d
Page({
data: {
a: 1,
b: 2,
c: 3
}
})
view中的内容为 3 + 3 + d
。算数运行也和其他语言一样, 只是要在外面包裹一层{{}}
5.3 逻辑判断
逻辑判断类似, 在外层包裹{{}}即可
5.4 字符串运算
{{"hello" + name}}
Page({
data: {
name: 'MINA'
}
})
这个 类似其他语言, 只是在外层包裹{{}}
上面语句运行后view标签显示hello MINA
5.5 数据路径运算
{{object.key}} {{array[0]}}
Page({
data: {
object: {
key: 'Hello '
},
array: ['MINA']
}
})
这个类似于字符串拼接
5.6 组合
也可以在 Mustache 内直接进行组合,构成新的对象或者数组。
5.7 数组
{{item}}
Page({
data: {
zero: 0
}
})
最终组合成数组[0, 1, 2, 3, 4]
。
5.8 对象
Page({
data: {
a: 1,
b: 2
}
})
最终组合成的对象是 {for: 1, bar: 2}
也可以用扩展运算符 ...
来将一个对象展开
Page({
data: {
obj1: {
a: 1,
b: 2
},
obj2: {
c: 3,
d: 4
}
}
})
最终组合成的对象是 {a: 1, b: 2, c: 3, d: 4, e: 5}
。
如果对象的 key 和 value 相同,也可以间接地表达。
Page({
data: {
foo: 'my-foo',
bar: 'my-bar'
}
})
最终组合成的对象是 {foo: 'my-foo', bar:'my-bar'}
。
注意:上述方式可以随意组合,但是如有存在变量名相同的情况,后边的会覆盖前面,如:
Page({
data: {
obj1: {
a: 1,
b: 2
},
obj2: {
b: 3,
c: 4
},
a: 5
}
})
最终组合成的对象是 {a: 5, b: 3, c: 6}
。
注意: 花括号和引号之间如果有空格,将最终被解析成为字符串
{{item}}
等同于
{{item}}
在组件上使用 wx:for
控制属性绑定一个数组,即可使用数组中各项的数据重复渲染该组件。
默认数组的当前项的下标变量名默认为 index
,数组当前项的变量名默认为 item
{{index}}: {{item.message}}
Page({
data: {
array: [{
message: 'foo',
}, {
message: 'bar'
}]
}
})
上面在页面显示:
注意:for="{{xxx}}" 一定要在{{}}外打上双引号
使用 wx:for-item
可以指定数组当前元素的变量名,
使用 wx:for-index
可以指定数组当前下标的变量名:
{{idx}}: {{itemName.message}}
wx:for
也可以嵌套,下边是一个九九乘法表
{{i}} * {{j}} = {{i * j}}
运行结果:
类似 block wx:if
,也可以将 wx:for
用在
标签上,以渲染一个包含多节点的结构块。例如:
{{index}}:
{{item}}
注意: block是虚拟的, 在页面结构并不会出现block标签
如果列表中项目的位置会动态改变或者有新的项目添加到列表中,并且希望列表中的项目保持自己的特征和状态(如 中的输入内容,
的选中状态),需要使用 wx:key
来指定列表中项目的唯一的标识符。
wx:key
的值以两种形式提供
*this
代表在 for 循环中的 item 本身,这种表示需要 item 本身是一个唯一的字符串或者数字,如:当数据改变触发渲染层重新渲染的时候,会校正带有 key 的组件,框架会确保他们被重新排序,而不是重新创建,以确保使组件保持自身的状态,并且提高列表渲染时的效率。
如不提供 wx:key
,会报一个 warning
, 如果明确知道该列表是静态,或者不必关注其顺序,可以选择忽略。
示例代码:
在开发者工具中预览效果
{{item.id}}
{{item}}
Page({
data: {
objectArray: [
{id: 5, unique: 'unique_5'},
{id: 4, unique: 'unique_4'},
{id: 3, unique: 'unique_3'},
{id: 2, unique: 'unique_2'},
{id: 1, unique: 'unique_1'},
{id: 0, unique: 'unique_0'},
],
numberArray: [1, 2, 3, 4]
},
switch(e) {
const length = this.data.objectArray.length
for (let i = 0; i < length; ++i) {
const x = Math.floor(Math.random() * length)
const y = Math.floor(Math.random() * length)
const temp = this.data.objectArray[x]
this.data.objectArray[x] = this.data.objectArray[y]
this.data.objectArray[y] = temp
}
this.setData({
objectArray: this.data.objectArray
})
},
addToFront(e) {
const length = this.data.objectArray.length
this.data.objectArray = [{id: length, unique: 'unique_' + length}].concat(this.data.objectArray)
this.setData({
objectArray: this.data.objectArray
})
},
addNumberToFront(e) {
this.data.numberArray = [this.data.numberArray.length + 1].concat(this.data.numberArray)
this.setData({
numberArray: this.data.numberArray
})
}
})
注意:
当 wx:for
的值为字符串时,会将字符串解析成字符串数组
{{item}}
等同于
{{item}}
注意: 花括号和引号之间如果有空格,将最终被解析成为字符串
{{item}}
等同于
{{item}}
在框架中,使用 wx:if="{{condition}}"
来判断是否需要渲染该代码块:
True
也可以用 wx:elif
和 wx:else
来添加一个 else 块:
1
2
3
因为 wx:if
是一个控制属性,需要将它添加到一个标签上。如果要一次性判断多个组件标签,可以使用一个
标签将多个组件包装起来,并在上边使用 wx:if
控制属性。
view1
view2
注意:
并不是一个组件,它仅仅是一个包装元素,不会在页面中做任何渲染,只接受控制属性。
wx:if
vs hidden
因为 wx:if
之中的模板也可能包含数据绑定,所以当 wx:if
的条件值切换时,框架有一个局部渲染的过程,因为它会确保条件块在切换时销毁或重新渲染。
同时 wx:if
也是惰性的,如果在初始渲染条件为 false
,框架什么也不做,在条件第一次变成真的时候才开始局部渲染。
相比之下,hidden
就简单的多,组件始终会被渲染,只是简单的控制显示与隐藏。
一般来说,wx:if
有更高的切换消耗而 hidden
有更高的初始渲染消耗。因此,如果需要频繁切换的情景下,用 hidden
更好,如果在运行时条件不大可能改变则 wx:if
较好。
WXML提供模板(template),可以在模板中定义代码片段,然后在不同的地方调用。
使用 name 属性,作为模板的名字。然后在内定义代码片段,如:
{{index}}: {{msg}}
Time: {{time}}
使用 is 属性,声明需要的使用的模板,然后将模板所需要的 data 传入,如:
Page({
data: {
item: {
index: 0,
msg: 'this is a template',
time: '2016-09-15'
}
}
})
注意: 视图层和逻辑层数据绑定字段要相同
is 属性可以使用 Mustache 语法,来动态决定具体需要渲染哪个模板:
odd
even
模板拥有自己的作用域,只能使用 data 传入的数据以及模板定义文件中定义的
模块。
如bindtap
,当用户点击该组件的时候会在该页面对应的Page中找到相应的事件处理函数。
Click me!
Page({
tapName(event) {
console.log(event)
}
})
{
"type": "tap",
"timeStamp": 895,
"target": {
"id": "tapTest",
"dataset": {
"hi": "WeChat"
}
},
"currentTarget": {
"id": "tapTest",
"dataset": {
"hi": "WeChat"
}
},
"detail": {
"x": 53,
"y": 14
},
"touches": [
{
"identifier": 0,
"pageX": 53,
"pageY": 14,
"clientX": 53,
"clientY": 14
}
],
"changedTouches": [
{
"identifier": 0,
"pageX": 53,
"pageY": 14,
"clientX": 53,
"clientY": 14
}
]
}
事件分为冒泡事件和非冒泡事件:
WXML的冒泡事件列表:
类型 | 触发条件 | 最低版本 |
---|---|---|
touchstart | 手指触摸动作开始 | |
touchmove | 手指触摸后移动 | |
touchcancel | 手指触摸动作被打断,如来电提醒,弹窗 | |
touchend | 手指触摸动作结束 | |
tap | 手指触摸后马上离开 | |
longpress | 手指触摸后,超过350ms再离开,如果指定了事件回调函数并触发了这个事件,tap事件将不被触发 | 1.5.0 |
longtap | 手指触摸后,超过350ms再离开(推荐使用longpress事件代替) | |
transitionend | 会在 WXSS transition 或 wx.createAnimation 动画结束后触发 | |
animationstart | 会在一个 WXSS animation 动画开始时触发 | |
animationiteration | 会在一个 WXSS animation 一次迭代结束时触发 | |
animationend | 会在一个 WXSS animation 动画完成时触发 | |
touchforcechange | 在支持 3D Touch 的 iPhone 设备,重按时会触发 | 1.9.90 |
注:除上表之外的其他组件自定义事件如无特殊声明都是非冒泡事件,如的
submit
事件,的
input
事件,
的scroll
事件,(详见各个组件)
事件绑定的写法同组件的属性,以 key、value 的形式。
bind
或catch
开头,然后跟上事件的类型,如bindtap
、catchtouchstart
。自基础库版本 1.5.0 起,在非原生组件中,bind
和catch
后可以紧跟一个冒号,其含义不变,如bind:tap
、catch:touchstart
。bind
事件绑定不会阻止冒泡事件向上冒泡,catch
事件绑定可以阻止冒泡事件向上冒泡。
如在下边这个例子中,点击 inner view 会先后调用handleTap3
和handleTap2
(因为tap事件会冒泡到 middle view,而 middle view 阻止了 tap 事件冒泡,不再向父节点传递),点击 middle view 会触发handleTap2
,点击 outer view 会触发handleTap1
。
outer view
middle view
inner view
自基础库版本 1.5.0 起,触摸类事件支持捕获阶段。捕获阶段位于冒泡阶段之前,且在捕获阶段中,事件到达节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件时,可以采用capture-bind
、capture-catch
关键字,后者将中断捕获阶段和取消冒泡阶段。
在下面的代码中,点击 inner view 会先后调用handleTap2
、handleTap4
、handleTap3
、handleTap1
。
outer view
inner view
如果将上面代码中的第一个capture-bind
改为capture-catch
,将只触发handleTap2
。
outer view
inner view
如无特殊说明,当组件触发事件时,逻辑层绑定该事件的处理函数会收到一个事件对象。
BaseEvent 基础事件对象属性列表:
属性 | 类型 | 说明 |
---|---|---|
type | String | 事件类型 |
timeStamp | Integer | 事件生成时的时间戳 |
target | Object | 触发事件的组件的一些属性值集合 |
currentTarget | Object | 当前组件的一些属性值集合 |
CustomEvent 自定义事件对象属性列表(继承 BaseEvent):
属性 | 类型 | 说明 |
---|---|---|
detail | Object | 额外的信息 |
TouchEvent 触摸事件对象属性列表(继承 BaseEvent):
属性 | 类型 | 说明 |
---|---|---|
touches | Array | 触摸事件,当前停留在屏幕中的触摸点信息的数组 |
changedTouches | Array | 触摸事件,当前变化的触摸点信息的数组 |
特殊事件: 中的触摸事件不可冒泡,所以没有 currentTarget。
代表事件的类型。
页面打开到触发事件所经过的毫秒数。
触发事件的源组件。
属性 | 类型 | 说明 |
---|---|---|
id | String | 事件源组件的id |
tagName | String | 当前组件的类型 |
dataset | Object | 事件源组件上由data- 开头的自定义属性组成的集合 |
事件绑定的当前组件。
属性 | 类型 | 说明 |
---|---|---|
id | String | 当前组件的id |
tagName | String | 当前组件的类型 |
dataset | Object | 当前组件上由data- 开头的自定义属性组成的集合 |
说明: target 和 currentTarget 可以参考上例中,点击 inner view 时,handleTap3
收到的事件对象 target 和 currentTarget 都是 inner,而 handleTap2
收到的事件对象 target 就是 inner,currentTarget 就是 middle。
dataset
在组件中可以定义数据,这些数据将会通过事件传递给 SERVICE。 书写方式: 以data-
开头,多个单词由连字符-
链接,不能有大写(大写会自动转成小写)如data-element-type
,最终在 event.currentTarget.dataset 中会将连字符转成驼峰elementType
。
示例:
DataSet Test
Page({
bindViewTap(event) {
event.currentTarget.dataset.alphaBeta === 1 // - 会转为驼峰写法
event.currentTarget.dataset.alphabeta === 2 // 大写会转为小写
}
})
touches 是一个数组,每个元素为一个 Touch 对象(canvas 触摸事件中携带的 touches 是 CanvasTouch 数组)。 表示当前停留在屏幕上的触摸点。
Touch 对象
属性 | 类型 | 说明 |
---|---|---|
identifier | Number | 触摸点的标识符 |
pageX, pageY | Number | 距离文档左上角的距离,文档的左上角为原点 ,横向为X轴,纵向为Y轴 |
clientX, clientY | Number | 距离页面可显示区域(屏幕除去导航条)左上角距离,横向为X轴,纵向为Y轴 |
CanvasTouch 对象
属性 | 类型 | 说明 | 特殊说明 |
---|---|---|---|
identifier | Number | 触摸点的标识符 | |
x, y | Number | 距离 Canvas 左上角的距离,Canvas 的左上角为原点 ,横向为X轴,纵向为Y轴 |
changedTouches 数据格式同 touches。 表示有变化的触摸点,如从无变有(touchstart),位置变化(touchmove),从有变无(touchend、touchcancel)。
自定义事件所携带的数据,如表单组件的提交事件会携带用户的输入,媒体的错误事件会携带错误信息,详见组件定义中各个事件的定义。
点击事件的detail
带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。
WXML 提供两种文件引用方式import
和include
。
import
可以在该文件中使用目标文件定义的template
,如:
在 item.wxml 中定义了一个叫item
的template
:
{{text}}
在 index.wxml 中引用了 item.wxml,就可以使用item
模板:
import 有作用域的概念,即只会 import 目标文件中定义的 template,而不会 import 目标文件 import 的 template。
如:C import B,B import A,在C中可以使用B定义的template
,在B中可以使用A定义的template
,但是C不能使用A定义的template
。
A template
B template
include
可以将目标文件除了
外的整个代码引入,相当于是拷贝到 include
位置,如:
body
header
footer