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:
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 correspondingPage
.<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 fromBaseEvent
).Attribute Type Description detail Object Additional information TouchEvent
: List of touch event object properties (inherited fromBaseEvent
).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 totargetDataset 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
ObjectAttribute 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
ObjectAttribute 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 astouches
. 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
andtouchcancel
).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.