# 事件

事件将用户在渲染层的操作，反馈到逻辑层，触发对应的事件处理函数，进而响应用户的交互。事件对象可以传递额外的数据，如 id, dataset, touches。

# 事件使用示例

• 在组件中绑定一个事件处理函数，如bindtap="handleTap"

<view id="testView" data-hi="QuickApp" bindtap="handleTap">点击</view>

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

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

• 打印的 event 结构如下：

{
  "type": "tap",
  "timeStamp": 868,
  "target": {
    "id": "testView",
    "dataset": {
      "hi": "QuickApp"
    }
  },
  "currentTarget": {
    "id": "testView",
    "dataset": {
      "hi": "QuickApp"
    }
  },
  "detail": {
    "x": 59,
    "y": 36
  },
  "touches": [
    {
      "identifier": 0,
      "pageX": 59,
      "pageY": 36,
      "clientX": 59,
      "clientY": 36
    }
  ],
  "changedTouches": [
    {
      "identifier": 0,
      "pageX": 59,
      "pageY": 36,
      "clientX": 59,
      "clientY": 36
    }
  ]
}

# 使用 QJS 函数响应事件

使用 QJS 函数处理事件这种情况下，QJS 函数接受 2 个参数，第一个是 event 对象，event 除了有上面基本的属性外，还具有一个 instance 属性；第二个参数是 ownerInstance，和event.instance 一样是一个 ComponentDescriptor 对象。

代码示例：

• 在 qxml 中绑定 QJS 函数。

<qjs module="qjs" src="./test.qjs"></qjs>
<view id="testView" data-hi="QuickApp" bindtap="{{qjs.handleTap}}"> Click Button </view>

注意：绑定的 QJS 函数必须用{{}}括起来

• test.qjs 文件实现 handleTap 函数

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

ComponentDescriptor 对象拥有一些方法，可以设置组件的样式等。 更多详情请参考文档。

# 事件详解

# 事件分类

快应用渲染层中事件分为冒泡事件和非冒泡事件：

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

冒泡事件列表：

注：其他事件如无特殊声明都是非冒泡事件，如 form 的submit事件，input 的input事件，scroll-view 的scroll事件

# 事件绑定和冒泡

事件绑定的写法和组件的属性相同。

• key 以bind或catch开头，后面拼接事件的类型，如bindtap、catchtouchstart。bind和catch后也可以紧跟一个冒号，如bind:tap、catch:touchstart，作用一致。
• value 是一个字符串，需要在对应的 Page 中定义同名的函数。否则当触发事件的时候会报错。
• bind 与 catch 的区别：bind 事件绑定不会阻止冒泡事件向上冒泡，而 catch 则会。

代码示例：

<view id="view1" bindtap="handleTap1">
  view1
  <view id="view2" catchtap="handleTap2">
    view2
    <view id="view3" bindtap="handleTap3">
      view3
    </view>
  </view>
</view>

执行效果：

• 点击 view3 会先后调用handleTap3和handleTap2(这是因为 tap 事件会冒泡到 view2，而 view2 阻止了 tap 事件冒泡，不再向父节点 view1 传递)
• 点击 view2 只触发handleTap2
• 点击 view1 只触发handleTap1

# 事件的捕获阶段

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

示例代码：

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

执行效果：

• 点击 view3 会先后调用handleTap2、handleTap4、handleTap3、handleTap1

示例代码：(上面代码中的第一个capture-bind改为capture-catch)

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

执行效果：

• 点击 view3 只触发handleTap2

# 事件对象

当组件触发事件时，逻辑层绑定的处理函数会收到一个事件对象。

各属性详细信息如下。

# target

触发事件的源组件。

# currentTarget

事件绑定的当前组件。

说明： target 和 currentTarget 可以参考上例中，点击 view3 时，handleTap3 收到的事件对象 target 和 currentTarget 都是 view3，而 handleTap2 收到的事件对象 target 就是 view3，currentTarget 就是 view2。

# dataset

在组件节点中可以定义一些自定义数据，触发事件时会传入回调中处理。

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

• data-custom-value ，最终会呈现为 event.currentTarget.dataset.customValue ；
• data-customValue ，最终会呈现为 event.currentTarget.dataset.customvalue 。

# touches

touches 是一个数组，每个元素为一个 Touch 对象。 表示当前停留在屏幕上的触摸点。另外 canvas 触摸事件中携带的 touches 是 CanvasTouch 数组。

# Touch 对象

# CanvasTouch 对象

# changedTouches

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

# detail

自定义事件数据，详见组件定义中各个事件的定义。

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