All Products
Search
Document Center

Event

Last Updated: Feb 05, 2021

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.

  1. <view id="outter" onTap="handleTap1">
  2. view1
  3. <view id="middle" catchTap="handleTap2">
  4. view2
  5. <view id="inner" onTap="handleTap3">
  6. view3
  7. </view>
  8. </view>
  9. </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:

Type Triggering condition
touchStart Touch action starts
touchMove Moves after touching
touchEnd Touch action ends
touchcancel The touch action is interrupted such as by incoming call and pop-up dialog
tap Leaves immediately after touching
longTap Touches for more than 300 ms before leaving

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.

    1. <view id="tapTest" data-hi="Alipay" onTap="tapName">
    2. <view id="tapTestInner" data-hi="AlipayInner">
    3. Click me!
    4. </view>
    5. </view>
  • Write the event handler in the corresponding Page definition, in which the parameter should be event:

    1. Page({
    2. tapName(event) {
    3. console.log(event)
    4. }
    5. })

    You will see the following information in the log:

    1. {
    2. "type": "tap",
    3. "timeStamp": 13245456,
    4. "target": {
    5. "id": "tapTestInner",
    6. "dataset": {
    7. "hi": "Alipay"
    8. },
    9. "targetDataset": {
    10. "hi": "AlipayInner"
    11. }
    12. },
    13. "currentTarget": {
    14. "id": "tapTest",
    15. "dataset": {
    16. "hi": "Alipay"
    17. }
    18. }
    19. }

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:

  1. <view data-alpha-beta="1" data-alphaBeta="2" onTap="bindViewTap"> DataSet Test </view>
  1. Page({
  2. bindViewTap:function(event){
  3. event.target.dataset.alphaBeta === 1 // Hyphens are onverted into camel case
  4. event.target.dataset.alphabeta === 2 // The uppercase letters are converted to lowercase
  5. }
  6. })

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.