Mobile Platform as a Service:Event

What is an event?

• The event is the way how the view layer is communicated with the logical layer.

• The event can feed the user’s behavior back to the logical layer for processing.

• The event can be bound to components, and when the trigger condition is satisfied, the corresponding event handler in the logical layer is executed.

• The event objects can carry additional information such as id, dataset, and touches.

Usage

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

• Bubbling event: An event triggered on a component propagates up to its parent node.

• Non-bubbling event: An event triggered on a component does not propagate up to its parent node.

Event binding uses the same key-value format as component properties.

• The key starts with `on` or `catch`, followed by the event type, such as `onTap` or `catchTap`.

• The value is a string that specifies the name of a function. A function with this name must be defined in the corresponding Page object. Otherwise, an error occurs when the event is triggered.

An `on` event binding does not stop a bubbling event from propagating up. A `catch` event binding stops a bubbling event from propagating up.

<view id="outter" onTap="handleTap1">
  view1
  <view id="middle" catchTap="handleTap2">
    view2
    <view id="inner" onTap="handleTap3">
      view3
    </view>
  </view>
</view>

In the code example, tapping view3 triggers handleTap3 and then handleTap2. This is because the tap event propagates to view2, and the `catch` binding on view2 stops the event from bubbling up to the parent node. Tapping view2 triggers handleTap2, and tapping view1 triggers handleTap1.

List of bubbling events:

Other events do not bubble.

• Bind an event handler function in a component.

  For example, with onTap, tapping the component calls the corresponding event handler in the page's Page object.

  <view id="tapTest" data-hi="Alipay" onTap="tapName">
  <view id="tapTestInner" data-hi="AlipayInner">
    Click me!
  </view>
  </view>

• In the corresponding Page definition, define the event handler function. The parameter is `event`:

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

  The logged information is similar to the following:

  {
  "type": "tap",
  "timeStamp": 13245456,
  "target": {
    "id": "tapTestInner",
    "dataset": {
      "hi": "Alipay"
    },
    "targetDataset": {
      "hi": "AlipayInner"
    }
  },
  "currentTarget": {
    "id": "tapTest",
    "dataset": {
      "hi": "Alipay"
    }
  }
  }

Event object

When a component triggers an event, the event handler bound in the logic layer receives an event object.

• BaseEvent: A list of base event object properties.

  Property	Type	Description
  type	String	Event type
  timeStamp	Integer	Timestamp when the event was generated
  target	Object	A collection of property values from the component that triggered the event

• CustomEvent: A list of custom event object properties. This object inherits from BaseEvent.

  Property	Type	Description
  detail	Object	Extra information

• TouchEvent: A list of touch event object properties. This object inherits from BaseEvent.

  Property	Type	Description
  touches	Array	An array of information about the touch points currently on the screen
  changedTouches	Array	An array of information about the touch points that have changed

• type: The type of the event.

• timeStamp: The timestamp in milliseconds from when the page was opened to when the event was triggered.

• target: The source component that triggered the event.

  Property	Type	Description
  id	String	The ID of the event source component
  tagName	String	The type of the current component
  dataset	Object	A collection of custom properties starting with data- on the component where the event is bound
  targetDataset	Object	A collection of custom properties starting with data- on the component that actually triggered the event

dataset

You can define data in a component and pass it to the logic layer through an event.

Format: Start with data- and use hyphens (-) to separate words. Do not use uppercase letters, because they are automatically converted to lowercase. For example, data-element-type is converted to the camelCase elementType in event.target.dataset.

Code example:

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

Page({
  bindViewTap:function(event){
    event.target.dataset.alphaBeta === 1 // - is converted to camelCase
    event.target.dataset.alphabeta === 2 // Uppercase is converted to lowercase
  }
})

touches

touches is an array where each element is a Touch object. For canvas touch events, touches is an array of CanvasTouch objects. It represents the touch points currently on the screen.

• Touch object

  Property	Type	Description
  identifier	Number	The identifier for the touch point
  pageX, pageY	Number	The distance from the top-left corner of the document. The top-left corner is the origin. The horizontal axis is the X-axis, and the vertical axis is the Y-axis.
  clientX, clientY	Number	The distance from the top-left corner of the visible page area (the screen excluding the navigation bar). The horizontal axis is the X-axis, and the vertical axis is the Y-axis.

• CanvasTouch object

  Property	Type	Description
  identifier	Number	The identifier for the touch point
  x, y	Number	The distance from the top-left corner of the Canvas. The top-left corner of the Canvas is the origin. The horizontal axis is the X-axis, and the vertical axis is the Y-axis.

• changedTouches: The data format of changedTouches is the same as touches. It represents touch points that have changed, such as a new touch point (touchstart), a change in position (touchmove), or a touch point that has been removed (touchend or touchcancel).

• detail: The data carried by a custom event. For example, the submit event of a form component carries user input, and the error event of a media component carries an error message. For more information, see the event definitions in the documentation for each component.

Event capture phase

Starting from base libraries 2.8.9 and IDE 3.4.3, touch events can be triggered during the capture phase. The capture phase occurs before the bubbling phase. In the capture phase, the order in which the event reaches the nodes is the reverse of the bubbling phase. To listen for an event during the capture phase, use the `capture-on` or `capture-catch` keywords. The `capture-catch` keyword interrupts the capture phase and cancels the bubbling phase. In the code below, tapping the inner view calls `handleTap2`, `handleTap4`, `handleTap3`, and `handleTap1` in that order.

<view id="outer" onTouchStart="handleTap1" capture-onTouchStart="handleTap2">
  outer view
  <view id="inner" onTouchStart="handleTap3" capture-onTouchStart="handleTap4">
    inner view
  </view>
</view>

If you change the first `capture-on` to `capture-catch` in the code above, only `handleTap2` is triggered.

<view id="outer" onTouchStart="handleTap1" capture-catchTouchStart="handleTap2">
  outer view
  <view id="inner" onTouchStart="handleTap3" capture-onTouchStart="handleTap4">
    inner view
  </view>
</view>