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.

How to use

Events are divided into Bubbling events and Non-bubbling events:

• Bubbling event: When an event on a component is triggered, the event is passed to the parent node.

• Non-bubbling event: When an event on a component is triggered, the event is not passed to the parent node.

The event binding is written in the same way as the component’s properties, in the form of key and value.

• key begins with on or catch, and then followed by the type of event, such as onTap and catchTap.

• The value is a string that needs to define a function with the same name in the corresponding Page. Otherwise, an error will be reported when the event is triggered.

The on event binding does not prevent the propagation of bubbling event, while the catch event binding will prevent it.

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

In the above code, tapping view3 firstly triggers handleTap3 and then handleTap2 (because the tap event propagats to view2, which prevents the propagation of tap event, and the event will not propagate to the parent node). Tapping view2 triggers handleTap2 while tapping view1 triggers handleTap1.

Bubbling event list:

No bubbling for other events:

• Bind an event handler to the component.

  Take onTap for example, when the user taps the component, the event handler will be found in the corresponding Page.

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

• Write the event handler in the corresponding Page definition, in which the parameter should be event:

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

  You will see the following information in the log:

  {
  "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 handler bound to the event by the logic layer receives an event object.

• BaseEvent: List of basic event object properties.

  Attribute	Type	Description
  type	String	Event type
  timeStamp	Integer	Timestamp when the event was generated
  target	Object	A set of attribute values of the component that triggered the event

• CustomEvent: List of custom event object properties (inherited from BaseEvent).

  Attribute	Type	Description
  detail	Object	Additional information

• TouchEvent: List of touch event object properties (inherited from BaseEvent).

  Attribute	Type	Description
  touches	Array	An array of touch points that are currently on the screen
  changedTouches	Array	An array of touch points that are currently changed

• Type: Type of event.

• timeStamp: Number of milliseconds since page opening to event triggering.

• target: Source component that triggered the event.

  Attribute	Type	Description
  id	String	ID of the event source component
  tagName	String	Type of the current component
  dataset	Object	A set of custom properties starting with data- on the component that the event is bound to
  targetDataset	Object	A set of custom properties starting with data- on the component that actually triggered the event

dataset

Data can be defined in the component and will be passed to the logic layer through events.

Writing format: Starting with data-, multiple words are concatenated by a hyphen (-), words are in lowercase letter (the uppercase letters will automatically be converted to lowercase), such as data-element-type. In event.target.dataset, the hyphenated string will be converted into camel case elementType.

Code sample:

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

Page({
  bindViewTap:function(event){
    event.target.dataset.alphaBeta === 1 // Hyphens are onverted into camel case
    event.target.dataset.alphabeta === 2 // The uppercase letters are converted to lowercase
  }
})

touches

touches is an array, in which each element is a Touch object (the touches carried in canvas touch event is an array of CanvasTouch), and represents the touch points that are currently on the screen.

• Touch Object

  Attribute	Type	Description
  identifier	Number	Touch point identifier
  pageX, pageY	Number	The distance from the upper left corner of the document. The top left corner is the origin, the horizontal direction is the X axis, and the vertical direction is the Y axis.
  clientX, clientY	Number	The distance from the upper left corner of the displayable area in the page (navigation bar excluded). The horizontal direction is the X axis, and the vertical direction is the Y axis.

• CanvasTouch Object

  Attribute	Type	Description
  identifier	Number	Touch point identifier
  x, y	Number	The distance from the upper left corner of Canvas. The upper left corner of Canvas is the origin, the horizontal direction is the X axis, and the vertical direction is the Y axis.

• changedTouches: changedTouches has the same data format as touches. It indicates the touch points that are changed, such as from non-existence to existence (touchstart), position change (touchmove), and from existence to non-existence (touchend and touchcancel).

• detail: The data carried in the custom event. For example, the submission event of the form component carries the user’s input, and the error event of the media carries the error message. For details, see definition of each event in Component Definition.

Event capture phase

Starting with base library 2.8.9 and IDE 3.4.3, touch events can be triggered during the capture phase. The capture phase precedes the bubbling phase, and during the capture phase, events arrive at nodes in the reverse order compared to the bubbling phase. To listen for events during the capture phase, you can use the `capture-on` and `capture-catch` keywords; the latter will interrupt the capture phase and cancel the bubbling phase. In the code below, clicking the inner view will call `handleTap2`, `handleTap4`, `handleTap3`, and `handleTap1` in sequence.

<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` in the code above to `capture-catch`, only `handleTap2` will be triggered.

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