QQ小程序注册程序

QML（QQ Markup Language）

是框架设计的一套标签语言，结合基础组件、事件系统，可以构建出页面的结构。

::: tip tips:

QQ小程序同时兼容WXML标签语言。
QML的数据绑定，不能使用ECMAScript规范已经规定的关键字和保留字，使用了会提示Unexpected token或者Unexpected token: "tokenName", may be reserved words.的报错 ::: 用以下一些简单的例子来看看 QML 具有什么能力：

数据绑定

<!--qml-->
<view>{{message}}</view>

// page.js
Page({
  data: {
    message: 'Hello MINA!'
  }
})

列表渲染

<!--qml-->
<view qq:for="{{array}}">{{item}}</view>


// page.js
Page({
  data: {
    array: [1, 2, 3, 4, 5]
  }
})

条件渲染



<!--qml-->
<view qq:if="{{view == 'WEBVIEW'}}">WEBVIEW</view>
<view qq:elif="{{view == 'APP'}}">APP</view>
<view qq:else="{{view == 'MINA'}}">MINA</view>


// page.js
Page({
  data: {
    view: 'MINA'
  }
})

模板



<!--qml-->
<template name="staffName">
  <view>
    FirstName: {{firstName}}, LastName: {{lastName}}
  </view>
</template>


<template is="staffName" data="{{...staffA}}"></template>
<template is="staffName" data="{{...staffB}}"></template>
<template is="staffName" data="{{...staffC}}"></template>

// page.js
Page({
  data: {
    staffA: {firstName: 'Hulk', lastName: 'Hu'},
    staffB: {firstName: 'Shang', lastName: 'You'},
    staffC: {firstName: 'Gideon', lastName: 'Lin'}
  }
})

事件

<view bindtap="add">{{count}}</view>

Page({
  data: {
    count: 1
  },
  add(e) {
    this.setData({
      count: this.data.count + 1
    })
  }
})

具体的能力以及使用方式在以下章节查看：数据绑定、列表渲染、条件渲染、模板、事件、引用

数据绑定 QML 中的动态数据均来自对应 Page 的 data。

简单绑定

数据绑定使用 Mustache 语法（双大括号）将变量包起来，可以作用于：

内容

<view>{{ message }}</view>

Page({
  data: {
    message: 'Hello MINA!'
  }
})

组件属性(需要在双引号之内)

<view id="item-{{id}}"></view>

Page({
  data: {
    id: 0
  }
})

控制属性(需要在双引号之内)

<view qq:if="{{condition}}"></view>

Page({
  data: {
    condition: true
  }
})

关键字(需要在双引号之内) true：boolean 类型的 true，代表真值。 false： boolean 类型的 false，代表假值。

<checkbox checked="{{false}}"></checkbox>

运算

可以在 {{}} 内进行简单的运算，支持的有如下几种方式：

三元运算

<view hidden="{{flag ? true : false}}">Hidden</view>

算数运算

<view>{{a + b}} + {{c}} + d</view>

Page({
  data: {
    a: 1,
    b: 2,
    c: 3
  }
})




view中的内容为 3 + 3 + d。

逻辑判断

<view qq:if="{{length > 5}}"></view>

字符串运算

<view>{{"hello" + name}}</view>


1
2
Page({
  data: {
    name: 'MINA'
  }
})

数据路径运算
<view>{{object.key}} {{array[0]}}</view>


Page({
  data: {
    object: {
      key: 'Hello '
    },
    array: ['MINA']
  }
})

组合

也可以在 Mustache 内直接进行组合，构成新的对象或者数组。

数组

<view qq:for="{{[zero, 1, 2, 3, 4]}}">{{item}}</view>


Page({
  data: {
    zero: 0
  }
})

最终组合成数组[0, 1, 2, 3, 4]。

对象

<template is="objectCombine" data="{{for: a, bar: b}}"></template>

Page({
  data: {
    a: 1,
    b: 2
  }
})

最终组合成的对象是 {for: 1, bar: 2} 也可以用扩展运算符 ... 来将一个对象展开

<template is="objectCombine" data="{{...obj1, ...obj2, e: 5}}"></template>

Page({
  data: {
    obj1: {
      a: 1,
      b: 2
    },
    obj2: {
      c: 3,
      d: 4
    }
  }
})

最终组合成的对象是 {a: 1, b: 2, c: 3, d: 4, e: 5}。如果对象的 key 和 value 相同，也可以间接地表达。

<template is="objectCombine" data="{{foo, bar}}"></template>

Page({
  data: {
    foo: 'my-foo',
    bar: 'my-bar'
  }
})

最终组合成的对象是 {foo: 'my-foo', bar:'my-bar'}。注意：上述方式可以随意组合，但是如有存在变量名相同的情况，后边的会覆盖前面，如：

<view qq:for="{{[1,2,3]}} ">
  {{item}}
</view>

等同于

<view qq:for="{{[1,2,3] + ' '}}">
  {{item}}
</view>

列表渲染

qq:for

在组件上使用 qq:for 控制属性绑定一个数组，即可使用数组中各项的数据重复渲染该组件。默认数组的当前项的下标变量名默认为 index，数组当前项的变量名默认为 item

<view qq:for="{{array}}">
  {{index}}: {{item.message}}
</view>

Page({
  data: {
    array: [{
      message: 'foo',
    }, {
      message: 'bar'
    }]
  }
})

使用 qq:for-item 可以指定数组当前元素的变量名，
使用 qq:for-index 可以指定数组当前下标的变量名：
<view qq:for="{{array}}" qq:for-index="idx" qq:for-item="itemName">
  {{idx}}: {{itemName.message}}
</view>

qq:for 也可以嵌套，下边是一个九九乘法表
<view qq:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" qq:for-item="i">
  <view qq:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" qq:for-item="j">
    <view qq:if="{{i <= j}}">
      {{i}} * {{j}} = {{i * j}}
    </view>
  </view>
</view>

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

<block qq:for="{{[1, 2, 3]}}">
  <view>{{index}}:</view>
  <view>{{item}}</view>
</block>

qq:key

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

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

字符串，代表在 for 循环的 array 中 item 的某个 property，该 property 的值需要是列表中唯一的字符串或数字，且不能动态改变。
保留关键字 *this 代表在 for 循环中的 item 本身，这种表示需要 item 本身是一个唯一的字符串或者数字，如：当数据改变触发渲染层重新渲染的时候，会校正带有 key 的组件，框架会确保他们被重新排序，而不是重新创建，以确保使组件保持自身的状态，并且提高列表渲染时的效率。如不提供 qq:key，会报一个 warning，如果明确知道该列表是静态，或者不必关注其顺序，可以选择忽略。

示例代码：

<switch qq:for="{{objectArray}}" qq:key="unique" style="display: block;">
  {{item.id}}
</switch>
<button bindtap="switch">Switch</button>
<button bindtap="addToFront">Add to the front</button>


<switch qq:for="{{numberArray}}" qq:key="*this" style="display: block;">
  {{item}}
</switch>
<button bindtap="addNumberToFront">Add to the front</button>

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
    })
  }
})

注意：当 qq:for 的值为字符串时，会将字符串解析成字符串数组

<view qq:for="array">
  {{item}}
</view>

等同于

<view qq:for="{{['a','r','r','a','y']}}">
  {{item}}
</view>

注意：花括号和引号之间如果有空格，将最终被解析成为字符串

<view qq:for="{{[1,2,3]}} ">
  {{item}}
</view>

等同于

<view qq:for="{{[1,2,3] + ' '}}">
  {{item}}
</view>

条件渲染

qq:if

在框架中，使用 qq:if="" 来判断是否需要渲染该代码块：

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

也可以用 qq:elif 和 qq:else 来添加一个 else 块：

<view qq:if="{{length > 5}}">1</view>
<view qq:elif="{{length > 2}}">2</view>
<view qq:else>3</view>

block qq:if

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

<block qq:if="{{true}}">
  <view>view1</view>
  <view>view2</view>
</block>

注意： <block/> 并不是一个组件，它仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性。

qq:if vs hidden 因为 qq:if 之中的模板也可能包含数据绑定，所以当 qq:if 的条件值切换时，框架有一个局部渲染的过程，因为它会确保条件块在切换时销毁或重新渲染。同时 qq:if 也是惰性的，如果在初始渲染条件为 false，框架什么也不做，在条件第一次变成真的时候才开始局部渲染。相比之下，hidden 就简单的多，组件始终会被渲染，只是简单的控制显示与隐藏。一般来说，qq:if 有更高的切换消耗而 hidden 有更高的初始渲染消耗。因此，如果需要频繁切换的情景下，用 hidden 更好，如果在运行时条件不大可能改变则 qq:if 较好。

模板

QML提供模板（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}}" />

Page({
  data: {
    item: {
      index: 0,
      msg: 'this is a template',
      time: '2016-09-15'
    }
  }
})

is 属性可以使用 Mustache 语法，来动态决定具体需要渲染哪个模板：
<template name="odd">
  <view>odd</view>
</template>
<template name="even">
  <view>even</view>
</template>


<block qq:for="{{[1, 2, 3, 4, 5]}}">
  <template is="{{item % 2 == 0 ? 'even' : 'odd'}}" />
</block>

模板的作用域

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

事件

什么是事件

事件是视图层到逻辑层的通讯方式。事件可以将用户的行为反馈到逻辑层进行处理。事件可以绑定在组件上，当达到触发事件，就会执行逻辑层中对应的事件处理函数。事件对象可以携带额外信息，如 id, dataset, touches。

事件使用的方式

事件的使用方式在组件中绑定一个事件处理函数。如bindtap，当用户点击该组件的时候会在该页面对应的Page中找到相应的事件处理函数。

<view id="tapTest" data-hi="WeChat" bindtap="tapName">Click me!</view>

在相应的Page定义中写上相应的事件处理函数，参数是

event。
Page({
  tapName(event) {
    console.log(event)
  }
})

可以看到log出来的信息大致如下：
{
  "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
    }
  ]
}

使用QS函数响应事件 QS函数接受2个参数，第一个是event，在原有的event的基础上加了event.instance对象，第二个参数是ownerInstance，和event.instance一样是一个ComponentDescriptor对象。具体使用如下：

在组件中绑定和注册事件处理的QS函数。

<qs module="qs" src="./test.qs"></qs>
<view id="tapTest" data-hi="QQ" bindtap="{{qs.tapName}}">Click me!</view>
**注：绑定的QS函数必须用{{}}括起来**

test.qs文件实现tapName函数

function tapName(event, ownerInstance) {
  console.log('tap wechat', JSON.stringify(event))
}
module.exports = {
  tapName
}

ownerInstance包含了一些方法，可以设置组件的样式和class，具体包含的方法以及为什么要用QS函数响应事件，请点击查看详情。

事件详解

事件分类

事件分为冒泡事件和非冒泡事件：

冒泡事件：当一个组件上的事件被触发后，该事件会向父节点传递。

非冒泡事件：当一个组件上的事件被触发后，该事件不会向父节点传递。

QML的冒泡事件列表：

类型	触发条件
touchstart	手指触摸动作开始
touchmove	手指触摸后移动
touchcancel	手指触摸动作被打断，如来电提醒，弹窗
touchend	手指触摸动作结束
tap	手指触摸后马上离开
longpress	手指触摸后，超过350ms再离开，如果指定了事件回调函数并触发了这个事件，tap事件将不被触发
longtap	手指触摸后，超过350ms再离开（推荐使用longpress事件代替）
transitionend	会在 QSS transition 或 qq.createAnimation 动画结束后触发
animationstart	会在一个 QSS animation 动画开始时触发
animationiteration	会在一个 QSS animation 一次迭代结束时触发
animationend

会在一个 QSS animation 动画完成时触发

QQ小程序 注册程序

QML（QQ Markup Language）

数据绑定

列表渲染

条件渲染

模板

事件

简单绑定

运算

三元运算

算数运算

组合

数组

对象

列表渲染

qq:for

qq:key

条件渲染

qq:if

block qq:if

模板

定义模板

模板的作用域

事件

什么是事件

事件使用的方式

事件详解

事件分类

QQ小程序注册程序