小程序事件介绍

发表于 | 分类于
字数统计: 1,150 | 阅读时长 ≈ 5

事件

事件类型

冒泡事件

<canvas/> 的触摸事件不可冒泡

类型 触发条件 最低版本
touchstart 手指触摸动作开始
touchmove 手指触摸后移动
touchcancel 手指触摸动作被打断，如来电提醒，弹窗
touchend 手指触摸动作结束
tap 手指触摸后马上离开
longpress 手指触摸后，超过 350ms 再离开，如果指定了事件回调函数并触发了这个事件，tap事件将不被触发 1.5.0
longtap 手指触摸后，超过 350ms 再离开（推荐使用longpress事件代替）
transitionend 在 WXSS transition 或 wx.createAnimation 动画结束后触发
animationstart 在 WXSS animation 动画开始时触发
animationiteration 在 WXSS animation 一次周期结束时触发
animationend 在 WXSS animation 动画完成时触发

除上表之外的其他组件自定义事件如无特殊声明都是非冒泡事件，如 <form/> 的submit 事件，<input/> 的 input 事件，<scroll-view/> 的 scroll 事件，(详见各个组件)

事件绑定

冒泡事件绑定

通过 key=value 的形式绑定事件，key 可以是 bind 或 catch 开头，再加上事件类型，如 bindtap 、catchtouchstart 等；value 对应 Page 中定义的函数名

从基础库 1.5.0 开始，允许使用 key:value 的形式绑定事件

bind 和 catch 的区别在于：bind 无法阻止事件冒泡，catch 可以阻止冒泡事件

1
2
3
4
5
6
7
8
9
10
11
12
// 点击 inner view 会先后调用 tapInner 和 tapMiddle
// 点击 middle view 只会调用 tapMiddle

<view id="outer" bindtap="tapOut">
    outer view
    <view id="middle" catchtap="tapMiddle">
        middle view
        <view id="inner" bindtap="tapInner">
            inner view
        </view>
    </view>
</view>

mark

捕获事件绑定

自基础库 1.5.0 起，支持绑定触摸类型捕获事件；绑定的方式与冒泡事件略有差别，捕获事件的绑定是通过 capture-bind、capture-catch关键字实现

capture-catch 能中断捕获阶段和取消冒泡阶段

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 点击 inner view 先后调用 touchOutCapture、touchInnerCapture、touchInner、touchOut
<view id="outer" bind:touchstart="touchOut" capture-bind:touchstart="touchOutCapture">
    outer view
    <view id="inner" bind:touchstart="touchInner" capture-bind:touchstart="touchInnerCapture">
        inner view
    </view>
</view>


// 点击 inner view 只会调用 touchOutCapture
<view id="outer" bind:touchstart="touchOut" capture-catch:touchstart="touchOutCapture">
    outer view
    <view id="inner" bind:touchstart="touchInner" capture-catch:touchstart="touchInnerCapture">
        inner view
    </view>
</view>

mark

事件对象

当触发事件时，会给事件处理函数传递一个事件对象，事件对象具体包含内容如下：

由于 <canvas/> 的触摸事件不可冒泡，因此 <canvas/> 的触摸事件对象没有 currentTarget 属性

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

属性 类型 说明
type String 事件类型
timestamp Number 事件触发时的时间戳
target Object 触发事件的组件的一些属性集合
currentTarget Object 事件的当前目标组件的一些属性集合

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

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

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

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

target / currentTarget

元素自定义属性以 data- 开头，多个单词由连字符 - 链接，不能有大写(大写会自动转成小写)如 data-element-type，最终在 event.currentTarget.dataset 中会将连字符转成驼峰 elementType

属性 类型 说明
id String 元素或组件 ID
tagName String 元素或组件类型
dataset Object 元素或组件上自定义属性（data-）集合

touches

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

Touch 对象

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

CanvasTouch 对象

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

changedTouches

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

details

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

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