WXML

参考

参考文档：WXML语法参考

WXML 简介

WXML（WeiXin Markup Language）是框架设计的一套标签语言，结合基础组件、事件系统，可以构建出页面的结构。 ​一个完整的 WXML语句由一段开始标签和一段结束标签组成，在标签中可以是内容，也可以是其他的 WXML 语句，这一点上同 HTML 是一致的。

​标签可以拥有属性，属性提供了有关的 WXML元素更多信息。属性总是定义在开始标签中，除了一些特殊的属性外，其余属性的格式都是 key="value" 的方式成对出现。需要注意的是，WXML中的属性是大小写敏感的。

语法：<标签名 属性名1="属性值1" 属性名2="属性值2" ...> ...</标签名>

注意

没有被定义的变量的或者是被设置为 undefined 的变量不会被同步到 wxml 中

共同属性

所有wxml 标签都支持的属性称之为共同属性。

属性名	类型	描述
id	String	组件唯一表示
class	String	组件的样式类
style	String	组件的内联样式
hidden	Boolean	组件是否显示
data-*	Any	自定义属性
bind*/catch*	EventHandler	组件的事件

注释

<!-- 内容 -->

组件参考

基础组件参考

数据绑定

WXML 中的动态数据均来自对应 Page 的 data。
数据绑定使用 Mustache 语法（双大括号）将变量包起来。

<!-- 内容 -->
<view> {{ message }} </view>
<!-- 组件属性 -->
<view id="item-{{id}}"> </view>
<!-- 控制属性 -->
<view wx:if="{{condition}}"> </view>
<checkbox checked="{{false}}"> </checkbox>
<!-- 三元运算 -->
<view hidden="{{flag ? true : false}}"> Hidden </view>
<!-- 逻辑运算 -->
<view wx:if="{{length > 5}}"> </view>
<!-- 字符串运算 -->
<view>{{"hello" + name}}</view>
<!-- 组合 -->
<view wx:for="{{[zero, 1, 2, 3, 4]}}"> {{item}} </view>
<!-- 对象 -->
<template is="objectCombine" data="{{foo: a, bar: b}}"></template>

注意

特别注意：不要直接写 checked="false"，其计算结果是一个字符串，转成 boolean 类型后代表真值。

双向绑定

<input model:value="{{value}}" />

双向绑定有以下限制：

• 只能是一个单一字段的绑定
• 目前，尚不能 data 路径（比如引用对象的属性）

列表渲染

在组件上使用 wx:for 控制属性绑定一个数组，即可使用数组中各项的数据重复渲染该组件。

• 默认数组的当前项的下标变量名默认为 index，数组当前项的变量名默认为 item。
• 使用 wx:for-item 可以指定数组当前元素的变量名。
• 使用 wx:for-index 可以指定数组当前下标的变量名。

<view wx:for="{{array}}" wx:for-index="idx" wx:for-item="itemName">
  {{idx}}: {{itemName.message}}
</view>

提示

类似 block wx:if，也可以将 wx:for 用在 <block/> 标签上，以渲染一个包含多节点的结构块。

wx:key：
如果列表中项目的位置会动态改变或者有新的项目添加到列表中，并且希望列表中的项目保持自己的特征和状态（如 input 中的输入内容，switch 的选中状态），需要使用 wx:key 来指定列表中项目的唯一的标识符。

wx:key 的值以两种形式提供:

1. 字符串，代表在 for 循环的 array 中 item 的某个 property，该 property 的值需要是列表中唯一的字符串或数字，且不能动态改变。
2. 保留关键字 *this 代表在 for 循环中的 item 本身，这种表示需要 item 本身是一个唯一的字符串或者数字。

<!-- 方式1 -->
<switch wx:for="{{objectArray}}" wx:key="unique"> {{item.id}} </switch>

<!-- 方式2 -->
<switch wx:for="{{numberArray}}" wx:key="*this"> {{item}} </switch>

注

当数据改变触发渲染层重新渲染的时候，会校正带有 key 的组件，框架会确保他们被重新排序，而不是重新创建，以确保使组件保持自身的状态，并且提高列表渲染时的效率。

如不提供 wx:key，会报一个 warning， 如果明确知道该列表是静态，或者不必关注其顺序，可以选择忽略。

条件渲染

使用 wx:if="" 来判断是否需要渲染该代码块，也可以用 wx:elif 和 wx:else 来添加一个 else 块。

因为 wx:if 是一个控制属性，需要将它添加到一个标签上。如果要一次性判断多个组件标签，可以使用一个 <block/> 标签将多个组件包装起来，并在上边使用 wx:if 控制属性。

<view wx:if="{{condition}}"> True </view>

相关信息

wx:if 和 hidden 的区别wx:if是惰性的，渲染调成成立才会开始局部渲染，而hidden组件始终会被渲染。

模板

WXML提供模板（template），可以在模板中定义代码片段，然后在不同的地方调用。

定义模板

使用 name 属性，作为模板的名字。然后在<template/>内定义代码片段，如：

<!--
  index: int
  msg: string
  time: string
-->
<template name="msgItem">
  <view>
    <text> {{index}}: {{msg}} </text>
    <text> Time: {{time}} </text>
  </view>
</template>

使用模板

使用 is 属性，声明需要的使用的模板，然后将模板所需要的 data 传入，如：

<template is="msgItem" data="{{...item}}"/>

注意

模板拥有自己的作用域，只能使用 data 传入的数据以及模板定义文件中定义的 模块。

引用

WXML 提供两种文件引用方式 import 和 include。

import
import 可以在该文件中使用目标文件定义的template。

<import src="item.wxml"/>

注意

import 有作用域的概念，即只会 import 目标文件中定义的 template，而不会 import 目标文件 import 的 template。

include
include 可以将目标文件除了 <template/> <wxs/> 外的整个代码引入，相当于是拷贝到 include 位置。

<include src="footer.wxml"/>