# 事件

# 什么是事件

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

# 事件的使用方式

• 在組件中綁定一個(gè)事件處理函數(shù)。

如bindtap，當(dāng)用戶點(diǎn)擊該組件的時(shí)候會(huì)在該頁(yè)面對(duì)應(yīng)的Page中找到相應(yīng)的事件處理函數(shù)。

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

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

Page({
  tapName: function(event) {
    console.log(event)
  }
})

• 可以看到log出來(lái)的信息大致如下：

{
  "type":"tap",
  "timeStamp":895,
  "target": {
    "id": "tapTest",
    "dataset":  {
      "hi":"Weixin"
    }
  },
  "currentTarget":  {
    "id": "tapTest",
    "dataset": {
      "hi":"Weixin"
    }
  },
  "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
  }]
}

# 使用WXS函數(shù)響應(yīng)事件

基礎(chǔ)庫(kù) 2.4.4 開(kāi)始支持，低版本需做兼容處理。

從基礎(chǔ)庫(kù)版本2.4.4開(kāi)始，支持使用WXS函數(shù)綁定事件，WXS函數(shù)接受2個(gè)參數(shù)，第一個(gè)是event，在原有的event的基礎(chǔ)上加了event.instance對(duì)象，第二個(gè)參數(shù)是ownerInstance，和event.instance一樣是一個(gè)ComponentDescriptor對(duì)象。具體使用如下：

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

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

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

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

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

# 事件詳解

# 事件分類

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

1. 冒泡事件：當(dāng)一個(gè)組件上的事件被觸發(fā)后，該事件會(huì)向父節(jié)點(diǎn)傳遞。
2. 非冒泡事件：當(dāng)一個(gè)組件上的事件被觸發(fā)后，該事件不會(huì)向父節(jié)點(diǎn)傳遞。

WXML的冒泡事件列表：

注：除上表之外的其他組件自定義事件如無(wú)特殊聲明都是非冒泡事件，如 form 的submit事件，input 的input事件，scroll-view 的scroll事件，(詳見(jiàn)各個(gè)組件)

# 普通事件綁定

事件綁定的寫法類似于組件的屬性，如：

<view bindtap="handleTap">
    Click here!
</view>

如果用戶點(diǎn)擊這個(gè) view ，則頁(yè)面的 handleTap 會(huì)被調(diào)用。

事件綁定函數(shù)可以是一個(gè)數(shù)據(jù)綁定，如：

<view bindtap="{{ handlerName }}">
    Click here!
</view>

此時(shí)，頁(yè)面的 this.data.handlerName 必須是一個(gè)字符串，指定事件處理函數(shù)名；如果它是個(gè)空字符串，則這個(gè)綁定會(huì)失效（可以利用這個(gè)特性來(lái)暫時(shí)禁用一些事件）。

自基礎(chǔ)庫(kù)版本 1.5.0 起，在大多數(shù)組件和自定義組件中， bind 后可以緊跟一個(gè)冒號(hào)，其含義不變，如 bind:tap 。基礎(chǔ)庫(kù)版本 2.8.1 起，在所有組件中開(kāi)始提供這個(gè)支持。

# 綁定并阻止事件冒泡

除 bind 外，也可以用 catch 來(lái)綁定事件。與 bind 不同， catch 會(huì)阻止事件向上冒泡。

例如在下邊這個(gè)例子中，點(diǎn)擊 inner view 會(huì)先后調(diào)用handleTap3和handleTap2(因?yàn)閠ap事件會(huì)冒泡到 middle view，而 middle view 阻止了 tap 事件冒泡，不再向父節(jié)點(diǎn)傳遞)，點(diǎn)擊 middle view 會(huì)觸發(fā)handleTap2，點(diǎn)擊 outer view 會(huì)觸發(fā)handleTap1。

<view id="outer" bindtap="handleTap1">
  outer view
  <view id="middle" catchtap="handleTap2">
    middle view
    <view id="inner" bindtap="handleTap3">
      inner view
    </view>
  </view>
</view>

# 互斥事件綁定

自基礎(chǔ)庫(kù)版本 2.8.2 起，除 bind 和 catch 外，還可以使用 mut-bind 來(lái)綁定事件。一個(gè) mut-bind 觸發(fā)后，如果事件冒泡到其他節(jié)點(diǎn)上，其他節(jié)點(diǎn)上的 mut-bind 綁定函數(shù)不會(huì)被觸發(fā)，但 bind 綁定函數(shù)和 catch 綁定函數(shù)依舊會(huì)被觸發(fā)。

換而言之，所有 mut-bind 是“互斥”的，只會(huì)有其中一個(gè)綁定函數(shù)被觸發(fā)。同時(shí)，它完全不影響 bind 和 catch 的綁定效果。

例如在下邊這個(gè)例子中，點(diǎn)擊 inner view 會(huì)先后調(diào)用 handleTap3 和 handleTap2 ，點(diǎn)擊 middle view 會(huì)調(diào)用 handleTap2 和 handleTap1 。

<view id="outer" mut-bind:tap="handleTap1">
  outer view
  <view id="middle" bindtap="handleTap2">
    middle view
    <view id="inner" mut-bind:tap="handleTap3">
      inner view
    </view>
  </view>
</view>

# 事件的捕獲階段

自基礎(chǔ)庫(kù)版本 1.5.0 起，觸摸類事件支持捕獲階段。捕獲階段位于冒泡階段之前，且在捕獲階段中，事件到達(dá)節(jié)點(diǎn)的順序與冒泡階段恰好相反。需要在捕獲階段監(jiān)聽(tīng)事件時(shí)，可以采用capture-bind、capture-catch關(guān)鍵字，后者將中斷捕獲階段和取消冒泡階段。

在下面的代碼中，點(diǎn)擊 inner view 會(huì)先后調(diào)用handleTap2、handleTap4、handleTap3、handleTap1。

<view id="outer" bind:touchstart="handleTap1" capture-bind:touchstart="handleTap2">
  outer view
  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">
    inner view
  </view>
</view>

如果將上面代碼中的第一個(gè)capture-bind改為capture-catch，將只觸發(fā)handleTap2。

<view id="outer" bind:touchstart="handleTap1" capture-catch:touchstart="handleTap2">
  outer view
  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">
    inner view
  </view>
</view>

# 事件對(duì)象

如無(wú)特殊說(shuō)明，當(dāng)組件觸發(fā)事件時(shí)，邏輯層綁定該事件的處理函數(shù)會(huì)收到一個(gè)事件對(duì)象。

BaseEvent 基礎(chǔ)事件對(duì)象屬性列表：

CustomEvent 自定義事件對(duì)象屬性列表（繼承 BaseEvent）：

TouchEvent 觸摸事件對(duì)象屬性列表（繼承 BaseEvent）：

特殊事件： canvas 中的觸摸事件不可冒泡，所以沒(méi)有 currentTarget。

# type

代表事件的類型。

# timeStamp

頁(yè)面打開(kāi)到觸發(fā)事件所經(jīng)過(guò)的毫秒數(shù)。

# target

觸發(fā)事件的源組件。

# currentTarget

事件綁定的當(dāng)前組件。

說(shuō)明： target 和 currentTarget 可以參考上例中，點(diǎn)擊 inner view 時(shí)，handleTap3 收到的事件對(duì)象 target 和 currentTarget 都是 inner，而 handleTap2 收到的事件對(duì)象 target 就是 inner，currentTarget 就是 middle。

# dataset

在組件節(jié)點(diǎn)中可以附加一些自定義數(shù)據(jù)。這樣，在事件中可以獲取這些自定義的節(jié)點(diǎn)數(shù)據(jù)，用于事件的邏輯處理。

在 WXML 中，這些自定義數(shù)據(jù)以 data- 開(kāi)頭，多個(gè)單詞由連字符 - 連接。這種寫法中，連字符寫法會(huì)轉(zhuǎn)換成駝峰寫法，而大寫字符會(huì)自動(dòng)轉(zhuǎn)成小寫字符。如：

• data-element-type ，最終會(huì)呈現(xiàn)為 event.currentTarget.dataset.elementType ；
• data-elementType ，最終會(huì)呈現(xiàn)為 event.currentTarget.dataset.elementtype 。

示例：

<view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap"> DataSet Test </view>

Page({
  bindViewTap:function(event){
    event.currentTarget.dataset.alphaBeta === 1 // - 會(huì)轉(zhuǎn)為駝峰寫法
    event.currentTarget.dataset.alphabeta === 2 // 大寫會(huì)轉(zhuǎn)為小寫
  }
})

# mark

在基礎(chǔ)庫(kù)版本 2.7.1 以上，可以使用 mark 來(lái)識(shí)別具體觸發(fā)事件的 target 節(jié)點(diǎn)。此外， mark 還可以用于承載一些自定義數(shù)據(jù)（類似于 dataset ）。

當(dāng)事件觸發(fā)時(shí)，事件冒泡路徑上所有的 mark 會(huì)被合并，并返回給事件回調(diào)函數(shù)。（即使事件不是冒泡事件，也會(huì) mark 。）

代碼示例：

在開(kāi)發(fā)者工具中預(yù)覽效果

<view mark:myMark="last" bindtap="bindViewTap">
  <button mark:anotherMark="leaf" bindtap="bindButtonTap">按鈕</button>
</view>

在上述 WXML 中，如果按鈕被點(diǎn)擊，將觸發(fā) bindViewTap 和 bindButtonTap 兩個(gè)事件，事件攜帶的 event.mark 將包含 myMark 和 anotherMark 兩項(xiàng)。

Page({
  bindViewTap: function(e) {
    e.mark.myMark === "last" // true
    e.mark.anotherMark === "leaf" // true
  }
})

mark 和 dataset 很相似，主要區(qū)別在于： mark 會(huì)包含從觸發(fā)事件的節(jié)點(diǎn)到根節(jié)點(diǎn)上所有的 mark: 屬性值；而 dataset 僅包含一個(gè)節(jié)點(diǎn)的 data- 屬性值。

細(xì)節(jié)注意事項(xiàng)：

• 如果存在同名的 mark ，父節(jié)點(diǎn)的 mark 會(huì)被子節(jié)點(diǎn)覆蓋。
• 在自定義組件中接收事件時(shí)， mark 不包含自定義組件外的節(jié)點(diǎn)的 mark 。
• 不同于 dataset ，節(jié)點(diǎn)的 mark 不會(huì)做連字符和大小寫轉(zhuǎn)換。

# touches

touches 是一個(gè)數(shù)組，每個(gè)元素為一個(gè) Touch 對(duì)象（canvas 觸摸事件中攜帶的 touches 是 CanvasTouch 數(shù)組）。 表示當(dāng)前停留在屏幕上的觸摸點(diǎn)。

# Touch 對(duì)象

# CanvasTouch 對(duì)象

# changedTouches

changedTouches 數(shù)據(jù)格式同 touches。 表示有變化的觸摸點(diǎn)，如從無(wú)變有（touchstart），位置變化（touchmove），從有變無(wú)（touchend、touchcancel）。

# detail

自定義事件所攜帶的數(shù)據(jù)，如表單組件的提交事件會(huì)攜帶用戶的輸入，媒體的錯(cuò)誤事件會(huì)攜帶錯(cuò)誤信息，詳見(jiàn)組件定義中各個(gè)事件的定義。

點(diǎn)擊事件的detail 帶有的 x, y 同 pageX, pageY 代表距離文檔左上角的距離。