RbGestureEvent.js

中文版本README_CN

A modern web gesture event library that supports advanced gestures such as long press, pinch, and rotate, mimicking the native event API for easy integration into web applications.

Design Goals

• Support Multiple Gestures: Such as long press, drag, pinch, rotate, etc.
• Consistent with DOM API: Mimics the usage pattern of addEventListener.
• Cross-Platform Compatibility: Provides consistent event handling logic for both PC and mobile.
• Modern Browser Support: Compatible with Chrome 79+ and does not use advanced syntax like nullish coalescing operator.
• Specific Optimization: Currently a custom library for some projects, but also easy to integrate into other projects.

Supported Gesture List

The following are the gesture event types that can be bound:

Gesture Type	Description
press	Triggered when the element is pressed
release	Triggered when the element is released
click	Triggered when the element is clicked
doubleclick	Triggered on double, quadruple, etc. even number of clicks
longtouch	Triggered on long press
dragstart	Triggered when single-finger drag starts
dragend	Triggered when single-finger drag ends
dragmove	Triggered during single-finger drag
doubeldragstart	Triggered when double-finger drag starts
doubeldragend	Triggered when double-finger drag ends
doubeldragmove	Triggered during double-finger drag
swipeup	Triggered on fast upward swipe
swipedown	Triggered on fast downward swipe
swipeleft	Triggered on fast leftward swipe
swiperight	Triggered on fast rightward swipe
pinchstart	Triggered when pinch gesture starts
pinchin	Triggered on pinch in
pinchout	Triggered on pinch out
rotatestart	Triggered when rotate gesture starts
rotatemove	Triggered during rotation
rotateend	Triggered when rotate gesture ends

IMPORTANT：If you want to prevent the default longtouch event, please call event.preventDefault() in the press event, not in the longtouch event.

Usage

Import the Library

$ npm i rb-gesture-event --save

import { RbGestureEvent } from "rb-gesture-event";
// RbGestureEvent is the main gesture event class

const yourElement = document.querySelector('your-element');

Bind Events

// RbGestureEvent.registerEventListener(element, 'eventType', eventHandler);
// See the table for event types
// The event handler receives an RbEventState object, see below for details
// Similar to the native API, the event handler's `this` is bound to the registered element
RbGestureEvent.registerEventListener(yourElement, 'click', eventSate => {
    console.log('click');
});

Cancel Event Listener

const funcClick = eventSate => {
   console.log('click');
}
// To cancel an event, pass the same event handler, only the same reference can be recognized as the same function
RbGestureEvent.registerEventListener(yourElement, 'click', funcClick);
RbGestureEvent.cancelEventListener(yourElement, 'click', funcClick);

Event State Object (RbEventState)

The event handler receives an RbEventState object, which contains the following information:

Property	Type	Description
eventType	String	Current event type
scale	Number	Current scale ratio
deltaAngle	Number	Change in angle relative to the initial angle
midPoint	Array<Number>	Midpoint coordinates of two fingers
midDisplacement	Array<Number>	Displacement of the midpoint of two fingers
clickCount	Number	Current click count
isRotate	Boolean	Whether it is rotating
isPinch	Boolean	Whether it is pinching
pointers	Map<Number, PointerInfo>	All pointer information
triggerPointer	PointerInfo	Pointer information that triggered this event
originEvent	PointerEvent	Original pointer event object

RbEventState.pointers is a Map structure that stores the id of each pointer and the corresponding PointerInfo object

Pointer Information Object (PointerInfo)

The project uses PointerInfo to store pointer parameters, which contain the following information:

Property	Type	Description
move	Boolean	Whether the pointer has moved
velocity	Array<Number>	Current movement speed of the pointer
displacement	Array<Number>	Pointer displacement
location	Array<Number>	Pointer location

Debugging Assistance

Use the following code to output additional debugging information.

Includes version information when enabled, warnings for duplicate event registrations, and warnings for overriding original judgment conditions.

// EXAMPLE: Enable debug mode
RbGestureEvent.setDebug(true); // Set to false to disable

Custom Configuration

Use the static method RbGestureEvent.setConfig to modify the threshold for event recognition. The parameter is an object, as follows:

// EXAMPLE: Modify configuration
// Configurable items and default values
// static config = {
//    threshold: 5, // Minimum displacement required for recognition (unit: px)
//    swipeVelocityThreshold: 0.3, // Minimum speed required for swipe recognition (unit: px/ms)
//    clickThreshold: 500, // Maximum time for click recognition (unit: ms)
//    longtouchThreshold: 500, // Minimum time for longtouch recognition (unit: ms)
//    angleThreshold: 5, // Minimum angle required for rotation recognition (unit: deg)
//    scaleThreshold: 0.05, // Minimum scale change required for pinch recognition (unitless)
// }
RbGestureEvent.setConfig({
   // Config item: content
   // Config item: content
   // Config item: content
});

Custom Conditions (Advanced)

Modifying gesture conditions is not recommended to avoid affecting future version compatibility.

Add Custom Event Conditions

RbGestureEvent.setCondition('customEvent', (eventState, lastEventState, trigger) => {
    return eventState.pointerCount === 3; // Trigger only on three-finger touch
});

// RbGestureEvent.setCondition('eventName', (eventState: EventState, lastEventState: EventState, trigger: String) => Boolean);
// eventState: Current event state
// lastEventState: Previous event state - eventState is only updated when the pointer is pressed, moved, or released, while lastEventState is the previous eventState
// trigger: Trigger - The trigger is a string used to identify which event triggered this condition function call. It is different from eventState.eventType. eventState.eventType is the event type determined by the eventState update callback, which is bound to the body, while the trigger is determined by the element's event callback
// Return value: true to trigger the event, false not to trigger the event

Remove Custom Event Conditions

RbGestureEvent.removeCondition('customEvent');

Examples

Project DEMO

Code in the article

Project Structure

This project only has one mjs file, just copy it in and use it.

Contribution

• Feedback and improvement suggestions are welcome through PR and Issue.

License

MIT License. For details, please refer to the LICENSE file.