QQ小程序 注冊程序

QML（QQ Markup Language）

是框架設(shè)計的一套標(biāo)簽語言，結(jié)合基礎(chǔ)組件、事件系統(tǒng)，可以構(gòu)建出頁面的結(jié)構(gòu)。

::: tip tips:

• QQ小程序同時兼容WXML標(biāo)簽語言。
• QML的數(shù)據(jù)綁定，不能使用ECMAScript規(guī)范已經(jīng)規(guī)定的關(guān)鍵字和保留字 ，使用了會提示Unexpected token或者Unexpected token: "tokenName", may be reserved words.的報錯 ::: 用以下一些簡單的例子來看看 QML 具有什么能力：

數(shù)據(jù)綁定

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

具體的能力以及使用方式在以下章節(jié)查看： 數(shù)據(jù)綁定、列表渲染、條件渲染、模板、事件、引用

數(shù)據(jù)綁定 QML 中的動態(tài)數(shù)據(jù)均來自對應(yīng) Page 的 data。

簡單綁定

數(shù)據(jù)綁定使用 Mustache 語法（雙大括號）將變量包起來，可以作用于：

內(nèi)容

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

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

組件屬性(需要在雙引號之內(nèi))

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

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

控制屬性(需要在雙引號之內(nèi))

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

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

關(guān)鍵字(需要在雙引號之內(nèi)) true：boolean 類型的 true，代表真值。 false： boolean 類型的 false，代表假值。

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

運算

可以在 {{}} 內(nèi)進行簡單的運算，支持的有如下幾種方式：

三元運算

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

算數(shù)運算

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

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




view中的內(nèi)容為 3 + 3 + d。

邏輯判斷

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

字符串運算

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


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

數(shù)據(jù)路徑運算
<view>{{object.key}} {{array[0]}}</view>


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

組合

也可以在 Mustache 內(nèi)直接進行組合，構(gòu)成新的對象或者數(shù)組。

數(shù)組

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


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

最終組合成數(shù)組[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 相同，也可以間接地表達(dá)。

<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 控制屬性綁定一個數(shù)組，即可使用數(shù)組中各項的數(shù)據(jù)重復(fù)渲染該組件。 默認(rèn)數(shù)組的當(dāng)前項的下標(biāo)變量名默認(rèn)為 index，數(shù)組當(dāng)前項的變量名默認(rèn)為 item

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

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

使用 qq:for-item 可以指定數(shù)組當(dāng)前元素的變量名，
使用 qq:for-index 可以指定數(shù)組當(dāng)前下標(biāo)的變量名：
<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/>標(biāo)簽上，以渲染一個包含多節(jié)點的結(jié)構(gòu)塊。例如：

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

qq:key

如果列表中項目的位置會動態(tài)改變或者有新的項目添加到列表中，并且希望列表中的項目保持自己的特征和狀態(tài)（如 <input> 中的輸入內(nèi)容，<switch> 的選中狀態(tài)），需要使用 qq:key 來指定列表中項目的唯一的標(biāo)識符。

qq:key 的值以兩種形式提供

• 字符串，代表在 for 循環(huán)的 array 中 item 的某個 property，該 property 的值需要是列表中唯一的字符串或數(shù)字，且不能動態(tài)改變。
• 保留關(guān)鍵字 *this 代表在 for 循環(huán)中的 item 本身，這種表示需要 item 本身是一個唯一的字符串或者數(shù)字，如： 當(dāng)數(shù)據(jù)改變觸發(fā)渲染層重新渲染的時候，會校正帶有 key 的組件，框架會確保他們被重新排序，而不是重新創(chuàng)建，以確保使組件保持自身的狀態(tài)，并且提高列表渲染時的效率。 如不提供 qq:key，會報一個 warning， 如果明確知道該列表是靜態(tài)，或者不必關(guān)注其順序，可以選擇忽略。

示例代碼：

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

注意： 當(dāng) qq:for 的值為字符串時，會將字符串解析成字符串?dāng)?shù)組

<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 是一個控制屬性，需要將它添加到一個標(biāo)簽上。如果要一次性判斷多個組件標(biāo)簽，可以使用一個 <block/> 標(biāo)簽將多個組件包裝起來，并在上邊使用 qq:if 控制屬性。

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

注意： <block/> 并不是一個組件，它僅僅是一個包裝元素，不會在頁面中做任何渲染，只接受控制屬性。

qq:if vs hidden 因為 qq:if 之中的模板也可能包含數(shù)據(jù)綁定，所以當(dāng) qq:if 的條件值切換時，框架有一個局部渲染的過程，因為它會確保條件塊在切換時銷毀或重新渲染。 同時 qq:if 也是惰性的，如果在初始渲染條件為 false，框架什么也不做，在條件第一次變成真的時候才開始局部渲染。 相比之下，hidden 就簡單的多，組件始終會被渲染，只是簡單的控制顯示與隱藏。 一般來說，qq:if 有更高的切換消耗而 hidden 有更高的初始渲染消耗。因此，如果需要頻繁切換的情景下，用 hidden 更好，如果在運行時條件不大可能改變則 qq:if 較好。

模板

QML提供模板（template），可以在模板中定義代碼片段，然后在不同的地方調(diào)用。

定義模板

使用 name 屬性，作為模板的名字。然后在<template/>內(nèi)定義代碼片段，如：

<!--
  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 語法，來動態(tài)決定具體需要渲染哪個模板：
<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 傳入的數(shù)據(jù)以及模板定義文件中定義的 <qs /> 模塊。

事件

什么是事件

事件是視圖層到邏輯層的通訊方式。 事件可以將用戶的行為反饋到邏輯層進行處理。 事件可以綁定在組件上，當(dāng)達(dá)到觸發(fā)事件，就會執(zhí)行邏輯層中對應(yīng)的事件處理函數(shù)。 事件對象可以攜帶額外信息，如 id, dataset, touches。

事件使用的方式

事件的使用方式 在組件中綁定一個事件處理函數(shù)。 如bindtap，當(dāng)用戶點擊該組件的時候會在該頁面對應(yīng)的Page中找到相應(yīng)的事件處理函數(shù)。

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

在相應(yīng)的Page定義中寫上相應(yīng)的事件處理函數(shù)，參數(shù)是

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函數(shù)響應(yīng)事件 QS函數(shù)接受2個參數(shù)，第一個是event，在原有的event的基礎(chǔ)上加了event.instance對象，第二個參數(shù)是ownerInstance，和event.instance一樣是一個ComponentDescriptor對象。具體使用如下：

• 在組件中綁定和注冊事件處理的QS函數(shù)。

<qs module="qs" src="./test.qs"></qs>
<view id="tapTest" data-hi="QQ" bindtap="{{qs.tapName}}">Click me!</view>
**注：綁定的QS函數(shù)必須用{{}}括起來**

test.qs文件實現(xiàn)tapName函數(shù)

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

ownerInstance包含了一些方法，可以設(shè)置組件的樣式和class，具體包含的方法以及為什么要用QS函數(shù)響應(yīng)事件，請點擊查看詳情。

事件詳解

事件分類

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

• 冒泡事件：當(dāng)一個組件上的事件被觸發(fā)后，該事件會向父節(jié)點傳遞。

• 非冒泡事件：當(dāng)一個組件上的事件被觸發(fā)后，該事件不會向父節(jié)點傳遞。

QML的冒泡事件列表：

類型	觸發(fā)條件
touchstart	手指觸摸動作開始
touchmove	手指觸摸后移動
touchcancel	手指觸摸動作被打斷，如來電提醒，彈窗
touchend	手指觸摸動作結(jié)束
tap	手指觸摸后馬上離開
longpress	手指觸摸后，超過350ms再離開，如果指定了事件回調(diào)函數(shù)并觸發(fā)了這個事件，tap事件將不被觸發(fā)
longtap	手指觸摸后，超過350ms再離開（推薦使用longpress事件代替）
transitionend	會在 QSS transition 或 qq.createAnimation 動畫結(jié)束后觸發(fā)
animationstart	會在一個 QSS animation 動畫開始時觸發(fā)
animationiteration	會在一個 QSS animation 一次迭代結(jié)束時觸發(fā)
animationend

會在一個 QSS animation 動畫完成時觸發(fā)

touchforcechange 在支持 3D Touch 的 iPhone 設(shè)備，重按時會觸發(fā)