开发教程与代码示例

入门

小程序框架

框架概述

逻辑层

视图层

自定义组件

基础教程

能力教程

性能优化

安全

TTML-事件
收藏
我的收藏

什么是事件

•

事件是视图层到逻辑层的通讯方式。

•

事件可以将用户的行为反馈到逻辑层进行处理。

•

事件可以绑定在组件上，当触发事件，就会执行逻辑层中对应的事件处理函数。

•

事件对象可以携带额外信息，如 id, dataset, touches。

在组件上绑定事件

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

<!-- index.ttml -->
<view id="tapTest" data-hi="bytedance" bind:tap="tapName"> Click me! </view>

Page({
  tapName(event) {
    console.log(event);
  },
});

上面的 console.log 打印出来的 event 对象的信息大致如下：

{
  "type": "tap",
  "timeStamp": 895,
  "target": {
    "id": "tapTest",
    "dataset": {
      "hi": "bytedance"
    }
  },
  "currentTarget": {
    "id": "tapTest",
    "dataset": {
      "hi": "bytedance"
    }
  },
  "detail": {
    "x": 53,
    "y": 14
  },
  "touches": [
    {
      "identifier": 0,
      "pageX": 53,
      "pageY": 14,
      "clientX": 53,
      "clientY": 14
    }
  ],
  "changedTouches": [
    {
      "identifier": 0,
      "pageX": 53,
      "pageY": 14,
      "clientX": 53,
      "clientY": 14
    }
  ]
}

事件详情说明

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

•

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

•

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

冒泡事件

类型	触发条件
touchstart	手指触摸动作开始
touchmove	手指触摸后移动
touchcancel	手指触摸动作被打断，如来电提醒、弹窗等
touchend	手指触摸动作结束
tap	手指触摸后马上离开
longpress	手指触摸后，超过 350ms 再离开，如果指定了事件回调函数并触发了这个事件，tap 事件将不被触发
longtap	手指触摸后，超过 350ms 再离开（推荐使用 longpress 事件代替）
transitionend	会在 TTSS transition 或 tt.createAnimation 动画结束后触发
animationstart	会在一个 TTSS animation 动画开始时触发
animationiteration	会在一个 TTSS animation 一次迭代结束时触发
animationend	会在一个 TTSS animation 动画完成时触发
touchforcechange	在支持 3D Touch 的 iPhone 设备，重按时会触发

非冒泡事件

除了上表之外的其他组件的事件，如无特殊声明都是非冒泡事件，如 image 组件 load 事件，scroll-view 组件 scroll 事件，详情参考各个组件。

事件绑定和冒泡

事件绑定的写法同组件的属性，以 key、value 的形式。

•

key 以 bind或 catch或 capture-bind开头，然后跟上事件的类型，如 bindtap、catchtap。也可以在 bind 、 catch 和 capture-bind后紧跟一个冒号，如 bind:tap、catch:tap，其功能不变。

•

value 是一个字符串，需要在对应的 Page 中定义同名的函数。

事件功能如下：

功能	使用
绑定事件，冒泡阶段触发	bind:eventname
绑定事件，捕获阶段触发	capture-bind:eventname
绑定事件，在冒泡阶段触发，会阻止冒泡和取消默认行为	catch:eventname

事件绑定

用户点击 view2会先触发逻辑侧的 handleTap2 方法，然后触发handleTap1 方法。

<view id="wrap" bind:tap="handleTap1">
  view1
  <view id="module" bind:tap="handleTap2"> view2 </view>
</view>

事件绑定并阻止事件冒泡

用户点击 view2 只触发逻辑侧的 handleTap2 方法。

<view id="wrap" bind:tap="handleTap1">
  view1
  <view id="module" catch:tap="handleTap2"> view2 </view>
</view>

事件的捕获阶段

自基础库版本 2.66.0 起，触摸类事件支持捕获阶段，捕获阶段位于冒泡阶段之前，且在捕获阶段中，事件达到节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件，可以采用 capture-bind 关键字。

在下面代码中，点击 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>

新语法事件绑定

自基础库版本 2.66.0 起，将提供新的事件语法。新的事件语法具有拓展性强、易于理解特点。新语法事件绑定，以 key、value 的形式。

•

key 是 bind:eventname 或者bind:eventname.modifier 形式之一。事件的能力全部通过 modifier 进行表达，如 bind:tap.capture 表达在捕获阶段触发事件。

•

value 是一个字符串，需要在对应的 Page 中定义同名的函数。

modifier 可选值如下：

•

capture 捕获阶段触发事件

•

stop 阻止冒泡

•

prevent 阻止默认行为

modifier 不可以随意组合，某些组合是没有意义的。可使用的组合如下：

•

bind:eventname.stop.prevent = bind:eventname.prevent.stop 阻止冒泡和默认行为

新语法事件功能如下：

功能	使用
绑定事件，冒泡阶段触发	bind:eventname
绑定事件，捕获阶段触发	bind:eventname.capture
绑定事件，在冒泡阶段触发，取消默认行为	bind:eventname.prevent
绑定事件，在冒泡阶段触发，阻止冒泡	bind:eventname.stop
绑定事件，在冒泡阶段触发，会阻止事件冒泡和取消默认行为	bind:eventname.stop.prevent

普通事件绑定

用户点击 view2 会先触发逻辑侧的 handleTap2 方法，然后触发 handleTap1 方法。

<view id="wrap" bind:tap="handleTap1">
  view1
  <view id="module" bind:tap="handleTap2"> view2 </view>
</view>

绑定并阻止事件冒泡

用户点击view2 只触发逻辑侧的handleTap2 方法。

<view id="wrap" bind:tap="handleTap1">
  view1
  <view id="module" bind:tap.stop="handleTap2"> view2 </view>
</view>

事件捕获阶段

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

<view
  id="outer"
  bind:touchstart="handleTap1"
  bind:touchstart.capture="handleTap2"
>
  outer view
  <view
    id="inner"
    bind:touchstart="handleTap3"
    bind:touchstart.capture="handleTap4"
  >
    inner view
  </view>
</view>

阻止事件的默认行为

在下面代码中，点击 input 后由于阻止了默认行为，input 不会拉起软键盘。

<view bind:tap.prevent="handleTap1">
    <input style="width: 200px; height: 20px; border: 1px solid red"></input>
</view>

事件对象

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

BaseEvent 基础事件对象属性列表

属性	类型	说明
type	string	事件类型
timeStamp	number	事件生成时的时间戳
target	object	触发事件的组件的一些属性值集合
currentTarget	object	当前组件的一些属性值集合

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

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

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

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

特殊事件：<canvas/>中 currentTarget与 target 属性含义一致，都表示触发事件的组件属性集合。

事件对象属性

target

触发事件的组件的一些属性值集合。

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

currentTarget

事件绑定的当前组件。

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

dataset

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

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

•

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

•

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

示例：

<!-- index.ttml -->
<view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap">
  DataSet Test
</view>

Page({
  bindViewTap(event) {
    event.currentTarget.dataset.alphaBeta === 1; // - 会转为驼峰写法
    event.currentTarget.dataset.alphabeta === 2; // 大写转小写
  },
});

touches

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

Touch 对象

属性	类型	说明
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）等。

Bug & Tip

•

Tip：一个组件，基础库内部和开发者都绑定同一个事件情况下，执行顺序为先执行基础库内的事件然后执行开发者的事件回调。

TTML-事件收藏我的收藏