Events

What are Events?

• Events are a means of communication from the view layer to the logic layer.
• Events can transmit user actions to the logic layer for processing.
• Events can be bound to components, and when triggered, the corresponding event handling function in the logic layer is executed.
• Event objects can carry additional information such as id, dataset, and touches.

How to Use Events

• Bind an event handling function in a component.

For example, with 'tap', when a user clicks on the component, the corresponding event handling function in the Page associated with that page will be triggered.

<view id="tapTest" data-hi="Transsion" bind:tap="tapName">Click me!</view>

• In the corresponding Page definition, write the respective event handling function with 'event' as a parameter.

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

• The logged information will roughly resemble the following:

{
  "currentTarget": {
    "dataset": {
      "hi": "Transsion"
    }
  }
}

Event Details

Event Categories

Events are categorized into bubbling events and non-bubbling events:

1. Bubbling Events: When an event on a component is triggered, it propagates to its parent nodes.
2. Non-Bubbling Events: When an event on a component is triggered, it does not propagate to its parent nodes.

Bubbling events in DLT:

Type	Trigger Condition
touchstart	Finger touches start
touchmove	Finger touches and moves
touchend	Finger touches end
tap	Finger touches and leaves immediately

Note: Unless otherwise stated, all other custom events in components are non-bubbling events, such as the 'submit' event in a form, the 'input' event in an input, the 'scroll' event in a scroll-view, etc. (Refer to the documentation of each component for more details.)

Regular Event Binding

Event binding is similar to defining component attributes, for example:

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

If the user clicks this view, the 'handleTap' function in the page will be called.

Binding and Preventing Event Bubbling

Use .stop to prevent the event from bubbling up, and not to let the current element's event continue to trigger outward.

For example, in the following example, clicking on the inner view will call handleTap3 and handleTap2 in succession (because the tap event will bubble up to the middle view, and the middle view prevents the tap event from bubbling up, so it will not propagate to the parent node). Clicking on the middle view will trigger handleTap2, and clicking on the outer view will trigger handleTap1.

<view id="outer" class="item" bind:tap="handleTap1">
  outer view
  <view id="middle" class="item" bind:tap.stop="handleTap2">
    middle view
    <view id="inner" class="item" bind:tap="handleTap3">inner view</view>
  </view>
</view>

Event Capture Phase

Touch events support using .native.capture for event capture. Click events use click.native.capture for event capture. The capture phase is before the bubbling phase, and in the capture phase, the order in which events reach nodes is exactly the opposite of the bubbling phase. Also, if you want to interrupt and cancel the bubbling phase in the capture phase, you can use .stop in a chain.

For example, in the following example, touching or clicking the inner view will first execute handleTap1, then execute handleTap2.

<!-- Touch -->
<view id="outer" class="item" bind:touchstart.native.capture="handleTap1">
  outer view
  <view id="inner" class="item" bind:touchstart.native.capture="handleTap2">
    inner view
  </view>
</view>

<!-- Click -->
<view id="outer" class="item" bind:click.native.capture="handleTap1">
  outer view
  <view id="inner" class="item" bind:click.native.capture="handleTap2">
    inner view
  </view>
</view>

If you add .stop in a chain after the first capture in the above code, it will only execute handleTap1

<!-- Touch -->
<view id="outer" class="item" bind:touchstart.native.capture.stop="handleTap1">
  outer view
  <view id="inner" class="item" bind:touchstart.native.capture="handleTap2">
    inner view
  </view>
</view>

<!-- Click -->
<view id="outer" class="item" bind:click.native.capture.stop="handleTap1">
  outer view
  <view id="inner" class="item" bind:click.native.capture="handleTap2">
    inner view
  </view>
</view>

Event Object

Unless otherwise specified, when a component triggers an event, the event handling function bound to it in the logic layer will receive an event object.

dataset

Custom data can be attached to component nodes. This allows you to retrieve this custom node data in event handling for logic processing.

In DLT, these custom data start with 'data-' and use hyphens '-' to separate multiple words. For example:

• data-element-type, ultimately presented as event.currentTarget.dataset.elementtype;
• data-elementtype, ultimately presented as event.currentTarget.dataset.elementtype.

Example:

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

Page({
  bindViewTap: function (event) {
    event.currentTarget.dataset.alphabeta === 1; // Does not convert to camelCase
    event.currentTarget.dataset.alphabeta === 2; // Uppercase is converted to lowercase
  },
});

touches

Touches is an array, with each element being a Touch object (for canvas touch events, it's a CanvasTouch array). It represents the current touch points on the screen.

Touch Object

Property	Type	Description
pageX, pageY	Number	Distance from the document's top-left corner, with the document's top-left corner as the origin, X-axis horizontally, and Y-axis vertically.
clientX, clientY	Number	Distance from the top-left corner of the page's visible area (excluding the navigation bar), with X-axis horizontally and Y-axis vertically.

changedTouches

The format of changedTouches is the same as touches. It represents touch points that have changed, such as from none to some (touchstart), position change (touchmove), and from some to none (touchend, touchcancel).

detail

Custom data carried by the event, such as user input in form component's submit event or error information in media error events. Refer to the definitions of events in individual components for more details.