分类： 事件系统

事件处理函数的第一个参数是一个事件对象。

所有事件对象都具有以下属性：

触摸和点击类事件额外具有以下属性：

type

代表事件的类型。

timeStamp

一个时间戳，表示页面打开到触发事件所经过的毫秒数。

target

触发事件的源组件（即冒泡事件的起点）。以点击事件为例，它表示用户最终点击到的那个组件。

currentTarget

事件绑定的当前组件。它指代 bind 或 catch 事件绑定所在的那个组件。

对于非冒泡事件，currentTarget 和 target 相同。

在实践中，大多数情况下使用 currentTarget 更符合预期。

事件节点数据

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

有两种方式为节点附件自定义数据：dataset 和 mark。现在更推荐使用 mark。

dataset

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

• data-element-type ，最终会呈现为 event.currentTarget.dataset.elementType ；
• data-elementType ，最终会呈现为 event.currentTarget.dataset.elementtype 。

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

export default Page({
  bindViewTap:function(event){
    event.currentTarget.dataset.alphaBeta === 1 // 会转为驼峰写法
    event.currentTarget.dataset.alphabeta === 2 // 大写会转为小写
  }
})

在 glass-easel 组件框架中，可以使用 data: 写法，这种写法不会进行任何转换，通常更容易理解。

<view data:alphaBeta="1" bind:tap="bindViewTap"> DataSet Test </view>

export default Page({
  bindViewTap:function(event){
    event.currentTarget.dataset.alphaBeta === 1
  }
})

mark

在基础库版本 2.7.1 以上，可以使用 mark 来识别具体触发事件的 target 节点。此外，mark 还可以用于承载一些自定义数据（类似于 dataset）。

当事件触发时，事件冒泡路径上所有的 mark 会被合并，并返回给事件回调函数（即使事件不是冒泡事件，也会有这样的 mark 合并）。这使得 mark 通常比 dataset 更实用。

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

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

export default 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 对象，表示当前停留在屏幕上的触摸点。

changedTouches 与其类似，但是它包含所有变化的触摸点，包括从无变有（touchstart），位置变化（touchmove），从有变无（touchend、touchcancel）。

Touch 对象内部属性如下：

对于 canvas 组件生成的触摸类事件，Touch 对象还包含以下属性：

detail

表示事件的详细信息，它包含的字段根据事件的不同而不同。

自定义组件在 触发事件 时可以指定这个字段的值。

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

常用的微信小程序事件绑定类型是 bind 和 catch。它们的区别是，catch 会阻止事件冒泡，可参考 事件 。

在事件绑定中使用数据绑定

在事件绑定中，可以使用数据绑定来动态指定事件处理函数。

<view bind:tap="{{ handler }}">Click me</view>

此时，this.data.handler 应当是一个字符串，表示事件处理方法函数名。如果它是个空字符串，则这个绑定会失效：可以利用这个特性来暂时禁用一些事件。

互斥事件绑定

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

换而言之，所有 mut-bind 是“互斥”的，只会有其中一个绑定函数被触发。同时，它完全不影响 bind 和 catch 的绑定效果。

例如在下边这个例子中，点击 inner view 会先后调用 handleTap3 和 handleTap2 ，点击 middle view 会调用 handleTap2 和 handleTap1 。

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

事件的捕获阶段

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

在下面的代码中，点击 inner view 会先后调用 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>

如果将上面代码中的第一个 capture-bind 改为 capture-catch，将只触发 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>

事件系统是组件间通信的主要方式之一。组件可以触发任意的事件，组件的使用者可以监听这些事件。

关于事件的基本概念和用法，参见 事件 。

监听事件

监听自定义组件事件的方法与监听基础组件事件的方法完全一致，例如：

<component-tag-name bind:myevent="onMyEvent" />

export default Page({
  onMyEvent: function(e){
    e.detail // 自定义组件触发事件时提供的 detail 对象
  }
})

触发事件

自定义组件触发事件时，需要使用 triggerEvent 方法，指定事件名、detail 对象和事件选项，例如：

<button bind:tap="onTap"> 点击这个按钮将触发 myevent 事件 </button>

export default Component({
  properties: {},
  methods: {
    onTap: function(){
      const myEventDetail = {} // detail对象，提供给事件监听函数
      const myEventOption = {} // 触发事件的选项
      this.triggerEvent('myevent', myEventDetail, myEventOption)
    }
  }
})

触发事件的选项包括：

关于 bubbles 和 composed，可以参考下面这个例子。

<!-- 页面 page.wxml -->
<another-component bind:customevent="pageEventListener1">
  <my-component bind:customevent="pageEventListener2"></my-component>
</another-component>

<!-- 组件 another-component.wxml -->
<view bind:customevent="anotherEventListener">
  <slot />
</view>

<!-- 组件 my-component.wxml -->
<view bind:customevent="myEventListener">
  <slot />
</view>

// 组件 my-component.js
export default Component({
  methods: {
    onTap: function(){
      // 不冒泡
      // （只会触发 pageEventListener2）
      this.triggerEvent('customevent', {})

      // 在 Shadow 树上冒泡
      // （会依次触发 pageEventListener2、pageEventListener1）
      this.triggerEvent('customevent', {}, { bubbles: true })

      // 在 Composed 树上冒泡
      // （会依次触发 pageEventListener2、anotherEventListener、pageEventListener1）
      this.triggerEvent('customevent', {}, { bubbles: true, composed: true })
    }
  }
})

在独立任务中触发事件

triggerEvent 会同步触发事件。

有时候这会导致一些问题，例如，在属性 observer 或数据监听器中调用，可能会导致 递归更新问题 。此时，应该在一个独立的任务里触发事件，例如：

export default Component({
  properties: {
    foo: String,
  },
  observers: {
    foo() {
      // 如果直接在数据监听器中触发事件，可能会导致递归更新问题
      // 此时，可使用 nextTick 来在独立任务中触发事件
      wx.nextTick(() => {
        this.triggerEvent('customevent', {})
      })
    },
  },
})