What is an interaction event?

  • An event is a channel through which the view layer communicates with the logical layer.
  • An event can pass a user's action to the logical layer and trigger respective event handlers.
  • An event can be bound with a component. When the event is triggered, the specified event handler is executed at the logic layer.
  • An event object can carry additional information such as id, dataset, and touches.

Event types

Events are divided into bubbling events and non-bubbling ones.

  • Bubbling event: When an event is triggered on a component, this event is propagated to the component's parent node.
  • Non-bubbling event: When an event is triggered on a component, this event is not propagated to the component's parent node.

List of events

TypeTrigger condition
touchstartThe finger touch action starts.
touchmoveThe finger touches and moves.
touchcancelThe finger touch action is interrupted, such as incoming call reminders and pop-up windows.
touchendThe finger touch action ends.
tapThe finger leaves the screen immediately after a short tap.
transitionendThis event is triggered when a TYSS transition or createAnimation animation ends.
animationstartThis event is triggered when a TYSS animation starts.
animationiterationThis event is triggered when a TYSS animation is iterated.
animationendThis event is triggered when a TYSS animation ends.
longpressThe finger leaves the screen after it taps and holds on the screen for more than 350 ms. If an event callback function is specified and this event is triggered, the tap event is not triggered.2.13.0
longtapThe finger leaves the screen after it taps and holds on the screen for more than 350 ms (it is recommended to use longpress event instead).2.13.0

Note: Unless otherwise specified, the custom events of components other than those listed above are non-bubbling events. For example, the submit event of <form />, input event of <input />, and scroll event of scroll-view. For more information, see Components.

Event binding

An event can be bound by using the following two types of syntax:

  • bind:{event name} indicates to bind an event.
  • catch:{event name} indicates to bind an event and prevent the event from bubbling up.

Bind an event

Bind an event with bind:.

<view bind:tap="handleTap"> Click here!</view>

Bind an event and prevent bubbling

Bind an event with catch:.

For example:

  1. Tap inner view to call handleTap3 and handleTap2. Because the tap event is propagated to the middle view, whereas the middle view prevents the tap event from being propagated to the parent node.

  2. Tap middle view to trigger handleTap2.

  3. Tap outer view to trigger handleTap1.

    <view id="outer" bind:tap="handleTap1">
      outer view
      <view id="middle" catch:tap="handleTap2">
        middle view
        <view id="inner" bind:tap="handleTap3"> inner view </view>
      </view>
    </view>

Event object

Unless otherwise specified, when a component triggers an event, the handler bound with this event at the logic layer receives an event object.

List of BaseEvent object properties

PropertyTypeDescription
typeStringThe event type.
timeStampIntegerThe timestamp when an event occurs.
targetObjectA collection of property values of the component that triggers the event.
currentTargetObjectA collection of property values of the current component.

List of CustomEvent object properties (inherited from BaseEvent)

PropertyTypeDescription
detailObjectThe additional information.

List of TouchEvent object properties (inherited from BaseEvent)

PropertyTypeDescription
touchesArrayThe touch event. An array of information of touch points staying in the screen.
changedTouchesArrayThe touch event. An array of information of touch points involving changes in the screen.

type

The event type.

timeStamp

The number of milliseconds from the moment when the page is opened until the event is triggered.

target

The source component that triggers the event.

PropertyTypeDescription
idStringThe ID of the event source component.
datasetObjectA collection of custom properties starting with data- on the event source component.

currentTarget

The current component that is bound with the event.

PropertyTypeDescription
idStringThe ID of the current component.
datasetObjectA collection of custom properties starting with data- on the current component.

Note: You can refer to the above example for target and currentTarget. When users tap inner view, the event objects target and currentTarget received by handleTap3 are both inner, but the target and currentTarget received by handleTap2 are inner and middle, respectively.

dataset

You can add some custom data to the component node. This way, the custom node data can be obtained from the event, facilitating logical processing.

In the template, these custom data starts with data- and multiple words are joined with a hyphen -. In the code, a hyphenation is converted to camel case, and the uppercase characters are automatically converted to lowercase ones. Example:

  • data-element-type is converted to event.currentTarget.dataset.elementType.
  • data-elementType is converted to event.currentTarget.dataset.elementtype.

Example:

<view data-alpha-beta="1" data-alphaBeta="2" bind:tap="bindViewTap">
  DataSet Test
</view>
Page({
  bindViewTap: function (event) {
    event.currentTarget.dataset.alphaBeta === 1; // Convert hyphens (-) to camel case
    event.currentTarget.dataset.alphabeta === 2; // Convert uppercase to lowercase
  },
});

touches

touches is an array representing the touch points staying in the screen. Every element is a Touch object. touches in the canvas touch event is a CanvasTouch array.

Touch object

PropertyTypeDescription
identifierNumberThe identifier of a spcified touch point.
pageX, pageYNumberThe distance from the top left corner of the document. The top left corner of the document is the origin, with the horizontal line as X-axis and the vertical line as Y-axis.
clientX, clientYNumberThe distance from the top left corner of the page display area. The display area refers to the area on the screen without a navigation bar. The horizontal line serves as X-axis and the vertical line as Y-axis.

changedTouches

The data format of changedTouches is the same as that of touches. changedTouches indicates the touch points that have changes, such as touchstart (appearance of touch points), touchmove (location changes), and touchendor touchcancel (disappearance).

detail

The data that is carried by a custom event. For example, the submission event of a form component carries the user's input, and the error event of media carries the error message. For more information, see the event definitions in components.

The x and y in detail of the tap event are similar to pageX and pageY. x and y represent the distance from the top left corner of the document.

Example

Bind an event handler to the component

For example, bind:tap. When the user taps the component, the specified event handler will be found in the Page.

<view id="abc" data-hi="smart" bind:tap="handleTap"> Click me!</view>

In the Page definition, write the event handler with the parameter event.

Page({
  handleTap: function (event) {
    console.log(event);
  },
});

You can see that the event object from the log looks like this:

{
  "type": "tap",
  "timeStamp": 3817,
  "target": {
    "id": "abc",
    "offsetLeft": 105,
    "offsetTop": 197,
    "dataset": { "hi": "smart" }
  },
  "currentTarget": {
    "id": "abc",
    "offsetLeft": 105,
    "offsetTop": 197,
    "dataset": { "hi": "smart" }
  },
  "touches": [
    {
      "identifier": 0,
      "pageX": 243,
      "pageY": 209,
      "clientX": 243,
      "clientY": 209
    }
  ],
  "changedTouches": [
    {
      "identifier": 0,
      "pageX": 243,
      "pageY": 209,
      "clientX": 243,
      "clientY": 209
    }
  ]
}