小程序 事件



  • 定义和使用

    事件分为冒泡事件和非冒泡事件:
    1. 冒泡事件:当一个组件上的事件被触发后,该事件会向父节点传递。
    2. 非冒泡事件:当一个组件上的事件被触发后,该事件不会向父节点传递。
    WXML的冒泡事件列表:
    类型 触发条件
    touchstart 手指触摸动作开始
    touchmove 手指触摸后移动
    touchcancel 手指触摸动作被打断,如来电提醒,弹窗
    touchend 手指触摸动作结束
    tap 手指触摸后马上离开
    longpress 手指触摸后,超过350ms再离开,如果指定了事件回调函数并触发了这个事件,tap事件将不被触发
    longtap 手指触摸后,超过350ms再离开(推荐使用longpress事件代替)
    transitionend 会在 WXSS transition 或 wx.createAnimation 动画结束后触发
    animationstart 会在一个 WXSS animation 动画开始时触发
    animationiteration 会在一个 WXSS animation 一次迭代结束时触发
    animationend 会在一个 WXSS animation 动画完成时触发
    touchforcechange 在支持 3D Touch 的 iPhone 设备,重按时会触发
    注意:除上表之外的其他组件自定义事件如无特殊声明都是非冒泡事件,如 form 的submit事件,input 的input事件,scroll-view 的scroll事件,(详见各个组件)
  • 普通事件绑定

    事件绑定的写法类似于组件的属性,如:
    <view bindtap="handleTap">
    Click here!
    </view>
    
    
    如果用户点击这个 view ,则页面的 handleTap 会被调用。
    事件绑定函数可以是一个数据绑定,如:
    <view bindtap="{{ handlerName }}">
    Click here!
    </view>
    
    
    此时,页面的 this.data.handlerName 必须是一个字符串,指定事件处理函数名;如果它是个空字符串,则这个绑定会失效(可以利用这个特性来暂时禁用一些事件)。

    绑定并阻止事件冒泡

    除 bind 外,也可以用 catch 来绑定事件。与 bind 不同, catch 会阻止事件向上冒泡。
    例如在下边这个例子中,点击 inner view 会先后调用handleTap3和handleTap2(因为tap事件会冒泡到 middle view,而 middle view 阻止了 tap 事件冒泡,不再向父节点传递),点击 middle view 会触发handleTap2,点击 outer view 会触发handleTap1。
    <view id="outer" bindtap="handleTap1">
       outer view
       <view id="middle" catchtap="handleTap2">
         middle view
         <view id="inner" bindtap="handleTap3">
           inner view
         </view>
       </view>
     </view>
    
    
  • 事件对象

    如无特殊说明,当组件触发事件时,逻辑层绑定该事件的处理函数会收到一个事件对象。
    BaseEvent 基础事件对象属性列表:
    属性 类型 说明
    type String 事件类型
    timeStamp Integer 事件生成时的时间戳
    target Object 触发事件的组件的一些属性值集合
    currentTarget Object 当前组件的一些属性值集合
    mark Object 事件标记数据
    CustomEvent 自定义事件对象属性列表(继承 BaseEvent):
    属性 类型 说明
    detail Object 额外的信息

    target

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

    currentTarget

    事件绑定的当前组件。
    属性 类型 说明
    id String 当前组件的id
    dataset Object 当前组件上由data-开头的自定义属性组成的集合
    说明:target 和 currentTarget 可以参考上例中,点击 inner view 时,handleTap3 收到的事件对象 target 和 currentTarget 都是 inner,而 handleTap2 收到的事件对象 target 就是 inner,currentTarget 就是 middle。
  • dataset 和 detail

    在组件节点中可以附加一些自定义数据。这样,在事件中可以获取这些自定义的节点数据,用于事件的逻辑处理。
    在 WXML 中,这些自定义数据以 data- 开头,多个单词由连字符 - 连接。这种写法中,连字符写法会转换成驼峰写法,而大写字符会自动转成小写字符。如:
    <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 // 大写会转为小写
       }
     })
    
    

    detail

    自定义事件所携带的数据,如表单组件的提交事件会携带用户的输入,媒体的错误事件会携带错误信息,详见组件定义中各个事件的定义。
    点击事件的detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。