--- title: Basic Interaction Event --- ## What is an interaction event? - An event is a channel through which the view layer communicates with the logical layer. - An event can pass a user's action to the logical layer and trigger respective event handlers. - An event can be bound with a component. When the event is triggered, the specified event handler is executed at the logic layer. - An event object can carry additional information such as `id`, `dataset`, and `touches`. ## Event types Events are divided into bubbling events and non-bubbling ones. - Bubbling event: When an event is triggered on a component, this event is propagated to the component's parent node. - Non-bubbling event: When an event is triggered on a component, this event is not propagated to the component's parent node. ## List of events | Type | Trigger condition | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | | touchstart | The finger touch action starts. | | | touchmove | The finger touches and moves. | | | touchcancel | The finger touch action is interrupted, such as incoming call reminders and pop-up windows. | | | touchend | The finger touch action ends. | | | tap | The finger leaves the screen immediately after a short tap. | | | transitionend | This event is triggered when a TYSS transition or `createAnimation` animation ends. | | | animationstart | This event is triggered when a TYSS animation starts. | | | animationiteration | This event is triggered when a TYSS animation is iterated. | | | animationend | This event is triggered when a TYSS animation ends. | | | longpress | The finger leaves the screen after it taps and holds on the screen for more than 350 ms. If an event callback function is specified and this event is triggered, the tap event is not triggered. | 2.13.0 | | longtap | The finger leaves the screen after it taps and holds on the screen for more than 350 ms (it is recommended to use longpress event instead). | 2.13.0 | > **Note**: Unless otherwise specified, the custom events of components other than those listed above are non-bubbling events. For example, the `submit` event of `
`, `input` event of ``, and `scroll` event of `scroll-view`. For more information, see Components. ## Event binding An event can be bound by using the following two types of syntax: - `bind:{event name}` indicates to bind an event. - `catch:{event name}` indicates to bind an event and prevent the event from bubbling up. ### Bind an event Bind an event with `bind:`. ```html Click here! ``` ### Bind an event and prevent bubbling Bind an event with `catch:`. For example: 1. Tap `inner view` to call `handleTap3` and `handleTap2`. Because the `tap` event is propagated to the middle view, whereas the middle view prevents the `tap` event from being propagated to the parent node. 2. Tap `middle view` to trigger `handleTap2`. 3. Tap `outer view` to trigger `handleTap1`. ```html outer view middle view inner view ``` ## Event object Unless otherwise specified, when a component triggers an event, the handler bound with this event at the logic layer receives an event object. #### List of BaseEvent object properties | Property | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------- | | type | String | The event type. | | timeStamp | Integer | The timestamp when an event occurs. | | target | Object | A collection of property values of the component that triggers the event. | | currentTarget | Object | A collection of property values of the current component. | #### List of CustomEvent object properties (inherited from BaseEvent) | Property | Type | Description | | -------- | ------ | --------------------------- | | detail | Object | The additional information. | #### List of TouchEvent object properties (inherited from BaseEvent) | Property | Type | Description | | -------------- | ----- | ----------------------------------------------------------------------------------------- | | touches | Array | The touch event. An array of information of touch points staying in the screen. | | changedTouches | Array | The touch event. An array of information of touch points involving changes in the screen. | ### type The event type. ### timeStamp The number of milliseconds from the moment when the page is opened until the event is triggered. ### target The source component that triggers the event. | Property | Type | Description | | -------- | ------ | -------------------------------------------------------------------------------------- | | id | String | The ID of the event source component. | | dataset | Object | A collection of custom properties starting with `data-` on the event source component. | ### currentTarget The current component that is bound with the event. | Property | Type | Description | | -------- | ------ | --------------------------------------------------------------------------------- | | id | String | The ID of the current component. | | dataset | Object | A collection of custom properties starting with `data-` on the current component. | > **Note**: You can refer to the above example for `target` and `currentTarget`. When users tap `inner view`, the event objects `target` and `currentTarget` received by `handleTap3` are both `inner`, but the `target` and `currentTarget` received by `handleTap2` are `inner` and `middle`, respectively. ### dataset You can add some custom data to the component node. This way, the custom node data can be obtained from the event, facilitating logical processing. In the template, these custom data starts with `data-` and multiple words are joined with a hyphen `-`. In the code, a hyphenation is converted to camel case, and the uppercase characters are automatically converted to lowercase ones. Example: - `data-element-type` is converted to event.currentTarget.dataset.`elementType`. - `data-elementType` is converted to event.currentTarget.dataset.`elementtype`. Example: ```html DataSet Test ``` ```js Page({ bindViewTap: function (event) { event.currentTarget.dataset.alphaBeta === 1; // Convert hyphens (-) to camel case event.currentTarget.dataset.alphabeta === 2; // Convert uppercase to lowercase }, }); ``` ### touches `touches` is an array representing the touch points staying in the screen. Every element is a `Touch` object. `touches` in the `canvas` touch event is a `CanvasTouch` array. `Touch` object | Property | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | identifier | Number | The identifier of a spcified touch point. | | pageX, pageY | Number | The distance from the top left corner of the document. The top left corner of the document is the origin, with the horizontal line as X-axis and the vertical line as Y-axis. | | clientX, clientY | Number | The distance from the top left corner of the page display area. The display area refers to the area on the screen without a navigation bar. The horizontal line serves as X-axis and the vertical line as Y-axis. | ### changedTouches The data format of `changedTouches` is the same as that of `touches`. `changedTouches` indicates the touch points that have changes, such as `touchstart` (appearance of touch points), `touchmove` (location changes), and `touchend`or `touchcancel` (disappearance). ### detail The data that is carried by a custom event. For example, the submission event of a form component carries the user's input, and the error event of media carries the error message. For more information, see the event definitions in components. The `x` and `y` in `detail` of the tap event are similar to `pageX` and `pageY`. `x` and `y` represent the distance from the top left corner of the document. ## Example ### Bind an event handler to the component For example, `bind:tap`. When the user taps the component, the specified event handler will be found in the `Page`. ```html Click me! ``` In the `Page` definition, write the event handler with the parameter `event`. ```js Page({ handleTap: function (event) { console.log(event); }, }); ``` You can see that the `event` object from the `log` looks like this: ```json { "type": "tap", "timeStamp": 3817, "target": { "id": "abc", "offsetLeft": 105, "offsetTop": 197, "dataset": { "hi": "smart" } }, "currentTarget": { "id": "abc", "offsetLeft": 105, "offsetTop": 197, "dataset": { "hi": "smart" } }, "touches": [ { "identifier": 0, "pageX": 243, "pageY": 209, "clientX": 243, "clientY": 209 } ], "changedTouches": [ { "identifier": 0, "pageX": 243, "pageY": 209, "clientX": 243, "clientY": 209 } ] } ```