WeChat Open Platform

Mini Programs Documentation

Events

What are events?

  • Events are the method of communication between the view layer and the logical layer.
  • Events can feed user actions back to the logical layer for processing.
  • Events can be bound to components. When a trigger event is reached, the corresponding event processing function in the logical layer will be executed.
  • Event objects can carry additional information, such as ids, datasets, or touches.

Usage method for events

  • An event processing function is bound to a component.

For example, bindtap. When a user taps on this component, it will find the relevant event processing function in the Page corresponding to the page.

<view id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </view>
  • The parameter for the event processing function written in the corresponding Page definitions is event.
Page({
  tapName: function(event) {
    console.log(event)
  }
})
  • The information that comes out of the log is more or less as follows:
    {
    "type":"tap",
    "timeStamp":895,
    "target": {
      "id": "tapTest",
      "dataset":  {
        "hi":"WeChat"
      }
    },
    "currentTarget":  {
      "id": "tapTest",
      "dataset": {
        "hi":"WeChat"
      }
    },
    "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
    }]
    }
    

Event details

Event classification

Events are divided into bubble events and non-bubble events:

  1. Bubble event: after a component event is triggered, this event will be passed to the parent node.
  2. Non-bubble event: after a component event is triggered, this event will not be passed to the parent node.

WXML bubble event list:

Type Trigger condition
touchstart Started by finger touch action
touchmove Moved after finger touch
touchcancel Finger touch action interrupted, by call reminder or pop-up window, for example
touchend Ended by finger touch action
tap Leaves immediately after finger touch
longtap Leaves after finger touch if 350ms exceeded

Note: Other custom component events not included in the above table, including non-specific statements, are all non-bubble events, such as <form/> submit events, <input/> input events, and <scroll-view/> scroll events (see each component for details).

Event binding

Event writing is done in the same way as component attributes, in key or value form.

  • A key begins with bind or catch, then the event type follows, for example, bindtap or catchtouchstart.
  • A value is a string that needs a function with the same name defined in the corresponding Page, otherwise an error will be reported when an event is triggered.

bind event binding will not prevent bubble events from bubbling up. catch event binding can prevent bubble events from bubbling up.

In this example below, tapping on the inner view will trigger handleTap3 and handleTap2 in succession (because tap events will bubble to the middle view, the middle view has prevented the tap from bubbling and it will not be passed to the parent node again). Tapping on the middle view will trigger handleTap2, while tapping on the outer view will trigger handleTap1.

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

Event objects

If there are no special instructions, when a component triggers an event, the processing function that the logical layer binds to this event will receive an event object.

BaseEvent object attribute list:

Attribute Type Description
type String Event type
timeStamp Integer Time stamp for when the event was generated
target Object Some attribute value sets for the component that triggered an event
currentTarget Object Some attribute value sets for the current component

CustomEvent object attribute list (carried on from BaseEvent):

Attribute Type Description
detail Object Additional information

TouchEvent object attribute list (carried on from BaseEvent):

Attribute Type Description
touches Array Touch event, a touch point information array that currently stays on the screen
changedTouches Array Touch event, a currently changing touch point information array

Special events: <canvas/> Touch events in that cannot bubble, so there is no currentTarget.

type

Represents event type.

timeStamp

The number of milliseconds that pass from when the page is opened to when the event is triggered.

target

The source component for a trigger event.

Attribute Type Description
id String Event source component id
tagName String Current component type
dataset Object Set on the event source component composed of custom properties beginning with data-

currentTarget

Current event binding components.

Attribute Type Description
id String Current component id
tagName String Current component type
dataset Object Set on the current component composed of custom properties beginning with data-

Instructions: You can refer to the above example for the target and currentTarget. When the inner view is tapped on, the event objects target and currentTarget received by handleTap3 are both inner, while the event object target received by handleTap2 is inner and currentTarget is middle.

dataset

Data can be defined in the component, this data will be passed to SERVICE via the event. Writing method: data- used at the beginning, multiple words are linked by a hyphen symbol -, and capital letters cannot be used (capital letters will automatically be converted into lowercase letters). For example, data-element-type. In the end, hyphens will be converted into camel case in event.target.dataset. For example, elementType.

Example:

<view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap"> DataSet Test </view>
Page({
  bindViewTap:function(event){
    event.target.dataset.alphaBeta === 1 // - will turn into camel case
    event.target.dataset.alphabeta === 2 // capital letters will turn into lowercase letters
  }
})

touches

touches is an array, every element is a Touch object (the touches within canvas touch events are the CanvasTouch array). Touches indicate the touch points currently staying on the screen.

Touch objects
Attribute Type Description
identifier Number Touch point identifier
pageX, pageY Number The distance from the top left corner of the document, the top left corner of the document is the origin, the x-axis is horizontal and the y-axis is vertical
clientX, clientY Number The distance from the top left corner of the area of the page that can be displayed (the screen excluding the navigation bar), the x-axis is horizontal and the y-axis is vertical
CanvasTouch objects
Attribute Type Description Special instructions
identifier Number Touch point identifier
x, y Number The distance from the top left corner of the canvas, the top left corner of the canvas is the origin, the x-axis is horizontal and the y-axis is vertical

changedTouches

The changedTouches data format is the same as touches. It indicates that a touch point has changed, for example, from nothing to something (touchstart), a position change (touchmove), or from something to nothing (touchend, touchcancel).

detail

Data carried by custom events. For example, a form component submit event will carry user input and a media error event will carry the error information. See the definitions of each event in component definitions for more details.

The x, y and pageX, pageY brought by clicking on an event's detail represent the distance from the top left corner of the document.