事件

什么是事件

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

事件的使用方式

• 在组件中绑定一个事件处理函数。

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

<view id="vtap" data-name="MoreCross" bindtap="tapName"> 获取名字 </view>

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

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

• 可以看到log出来的信息大致如下：

{
  "type": "tap",
  "timeStamp": 1158,
  "mut": false,
  "target": {
    "id": "vtap",
    "dataset": {},
    "offsetLeft": 15,
    "offsetTop": 53
  },
  "currentTarget": {
    "dataset": {},
    "offsetLeft": 15,
    "offsetTop": 53
  },
  "mark": {},
  "detail": {
    "x": 70.90909576416016,
    "y": 61.45454788208008
  },
  "touches": [],
  "changedTouches": [
    {
      "identifier": 0,
      "force": 1,
      "screenX": 70.90909576416016,
      "screenY": 142.18182373046875,
      "clientX": 70.90909576416016,
      "clientY": 61.45454788208008,
      "pageX": 70.90909576416016,
      "pageY": 61.45454788208008,
      "radiusX": 0,
      "radiusY": 0,
      "rotationAngle": 0
    }
  ]
}

事件分类

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

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

MCML的冒泡事件列表：

注：除上表之外的其他组件自定义事件如无特殊声明都是非冒泡事件，如 <form/> 的 submit 事件, 的 <input/> 的 input 事件

普通事件绑定

事件绑定的写法类似于组件的属性，如：

<view bindtap="handleTap" bind:longpress="handleLongPress"> 点我 </view>

如果用户点击这个 view ，则页面的 handleTap 会被调用。

事件绑定函数可以是一个数据绑定，如：

<view bindtap="{{ handlerName }}"> 点我 </view>

此时，页面的 this.data.handlerName 必须是一个字符串，指定事件处理函数名；如果它是个空字符串，则这个绑定会失效（可以利用这个特性来暂时禁用一些事件）。 注意：bind 后可以紧跟一个冒号，其含义不变。

绑定并阻止事件冒泡

除 bind 外，也可以用 catch 来绑定事件。与 bind 不同， catch 会阻止事件向上冒泡。

例如在下边这个例子中，点击 inner view 会先后调用bubbleTap3和bubbleTap2(因为tap事件会冒泡到 middle view，而 middle view 阻止了 tap 事件冒泡，不再向父节点传递)，点击 middle view 会触发bubbleTap2，点击 outer view 会触发bubbleTap1。

<view id="outer" bindtap="bubbleTap1">
  outer view
  <view id="middle" catchtap="bubbleTap2">
      middle view
      <view id="inner" bindtap="bubbleTap3">
      inner view
      </view>
  </view>
</view>

互斥事件绑定

除 bind 和 catch 外，还可以使用 mut-bind 来绑定事件。一个 mut-bind 触发后，如果事件冒泡到其他节点上，其他节点上的 mut-bind 绑定函数不会被触发，但 bind 绑定函数和 catch 绑定函数依旧会被触发。

例如在下边这个例子中，点击 inner view 会先后调用 mutTap3 和 mutTap2 ，点击 middle view 会调用 mutTap2 和 mutTap 。

<view id="outer" mut-bind:tap="mutTap1">
  outer view
  <view id="middle" bindtap="mutTap2">
    middle view
    <view id="inner" mut-bind:tap="mutTap3">
      inner view
    </view>
  </view>
</view>

事件的捕获阶段

触摸类事件支持捕获阶段，捕获阶段位于冒泡阶段之前，且在捕获阶段中，事件到达节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件时，可以采用capture-bind、capture-catch关键字，后者将中断捕获阶段和取消冒泡阶段。

在下面的代码中，点击 inner view 会先后调用captureTap1、captureTap3、captureTap2。

<view id="outer" capture-bind:tap="captureTap1">
outer view
  <view id="middle" bind:tap="captureTap2">
    middle view
    <view id="inner" capture-bind:tap="captureTap3">
      inner view
    </view>
  </view>
</view>

如果将上面代码中的第一个capture-bind改为capture-catch，将只触发captureTap1。

<view id="outer" capture-catch:tap="captureTap1">
outer view
  <view id="middle" bind:tap="captureTap2">
    middle view
    <view id="inner" capture-bind:tap="captureTap3">
      inner view
    </view>
  </view>
</view>

事件对象

如无特殊说明，当组件触发事件时，逻辑层绑定该事件的处理函数会收到一个事件对象。

BaseEvent 基础事件对象属性列表：

CustomEvent 自定义事件对象属性列表（继承 BaseEvent）：

TouchEvent 触摸事件对象属性列表（继承 BaseEvent）：

type

代表事件的类型。

timeStamp

页面打开到触发事件所经过的毫秒数。

target

触发事件的源组件。

currentTarget

事件绑定的当前组件。

说明： target 和 currentTarget 可以参考上例中，点击 inner view 时，captureTap3 收到的事件对象 target 和 currentTarget 都是 inner，而 captureTap1 收到的事件对象 target 就是 inner，currentTarget 就是 outer。

dataset

在组件节点中可以附加一些自定义数据。这样，在事件中可以获取这些自定义的节点数据，用于事件的逻辑处理。

在 MCML 中，这些自定义数据以 data- 开头，多个单词由连字符 - 连接。这种写法中，连字符写法会转换成驼峰写法，而大写字符会自动转成小写字符。如：

• data-element-type ，最终会呈现为 event.currentTarget.dataset.elementType ；
• data-elementType ，最终会呈现为 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 // - 会转为驼峰写法
    event.currentTarget.dataset.alphabeta === 2 // 大写会转为小写
  }
})

mark

可以使用 mark 来识别具体触发事件的 target 节点。此外， mark 还可以用于承载一些自定义数据（类似于 dataset ）。 当事件触发时，事件冒泡路径上所有的 mark 会被合并，并返回给事件回调函数。（即使事件不是冒泡事件，也会 mark 。）

示例代码：

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

在上述 MCML 中，如果按钮被点击，将触发 bindViewTap 和 bindButtonTap 两个事件，事件携带的 event.mark 将包含 myMark 和 anotherMark 两项。

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

mark 和 dataset 很相似，主要区别在于： mark 会包含从触发事件的节点到根节点上所有的 mark: 属性值；而 dataset 仅包含一个节点的 data- 属性值。

细节注意事项：

• 如果存在同名的 mark ，父节点的 mark 会被子节点覆盖。
• 在自定义组件中接收事件时， mark 不包含自定义组件外的节点的 mark 。
• 不同于 dataset ，节点的 mark 不会做连字符和大小写转换。

touches

touches 是一个数组，每个元素为一个 Touch 对象。 表示当前停留在屏幕上的触摸点。

Touch 对象

CanvasTouch 对象

changedTouches

changedTouches 数据格式同 touches。 表示有变化的触摸点，如从无变有（touchstart），位置变化（touchmove），从有变无（touchend、touchcancel）。

detail

点击事件的detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。