事件

更新时间：2024-09-09 21:58:22

事件介绍

事件是视图层到逻辑层的通讯方式。
事件可以将用户的行为反馈到逻辑层进行处理。
事件对象可以携带额外信息，如 id dataset, touches。

代码示例：

<!-- .ksml -->
<button id="btnTest" data-hi="helloKS" bindtap="clickMe">Click me！</button>

// .js
Page({
  clickMe: function(event) {
    this.setData(event)
  }
})

事件分类

冒泡事件和非冒泡事件

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

KSML 的冒泡事件列表：

类型	触发条件
touchstart	手指触摸动作开始
touchmove	手指触摸后移动
touchcancel	手指触摸动作被打断，如来电提醒，弹窗
touchend	手指触摸动作结束
tap	手指触摸后马上离开
longpress	手指触摸后，超过 350ms 再离开
longtap	手指触摸后，超过 350ms 再离开（推荐使用 longpress 事件代替）
transitionend	会在 CSS transition 或 ks.createAnimation 动画结束后触发
animationstart	会在一个 CSS animation 动画开始时触发
animationiteration	会在一个 CSS animation 一次迭代结束时触发
animationend	会在一个 CSS animation 动画完成时触发

注：除上表之外的其他组件自定义事件如无特殊声明都是非冒泡事件

阻止事件冒泡

使用catchtap可以阻止冒泡

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

事件的捕获阶段

可以采用capture-bind、capture-catch关键字，后者将中断捕获阶段和取消冒泡阶段。

在下面的代码中，点击 inner view 会先后调用handleTap2、handleTap4、handleTap3、handleTap1。

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

事件对象

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

BaseEvent 基础事件对象属性列表

属性	类型	说明
type	String	事件类型
timeStamp	Integer	事件生成时的时间戳
target	Object	触发事件的组件的一些属性值集合
currentTarget	Object	当前组件的一些属性值集合
mark	Object	事件标记数据

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

属性	类型	说明
detail	Object	额外的信息

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

属性	类型	说明
touches	Array	触摸事件，当前停留在屏幕中的触摸点信息的数组
changedTouches	Array	触摸事件，当前变化的触摸点信息的数组

特殊事件： canvas 中的触摸事件不可冒泡，所以没有 currentTarget。

type

代表事件的类型。

timeStamp

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

target

触发事件的源组件。

属性	类型	说明
id	String	事件源组件的 id
dataset	Object	事件源组件上由 data-开头的自定义属性组成的集合

currentTarget

事件绑定的当前组件。

属性	类型	说明
id	String	当前组件的 id
dataset	Object	当前组件上由 data-开头的自定义属性组成的集合

dataset

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

在 KSML 中，这些自定义数据以 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 // 大写会转为小写
  }
})

touches

属性	类型	说明
identifier	Number	触摸点的标识符
pageX, pageY	Number	距离文档左上角的距离，文档的左上角为原点 ，横向为 X 轴，纵向为 Y 轴
clientX, clientY	Number	距离页面可显示区域（屏幕除去导航条）左上角距离，横向为 X 轴，纵向为 Y 轴

CanvasTouch 对象

属性	类型	说明
identifier	Number	触摸点的标识符
x, y	Number	距离 Canvas 左上角的距离，Canvas 的左上角为原点 ，横向为 X 轴，纵向为 Y 轴

changedTouches

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

detail

自定义事件所携带的数据，如表单组件的提交事件会携带用户的输入，媒体的错误事件会携带错误信息，详见组件定义中各个事件的定义。

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