@sol-parts/sol-stimulus-components · документація
Контролер swipe
Перетворює жести миші й тачскріна на Stimulus-події: swipeLeft/Right/Up/Down, координати перетягування та click. Без залежностей, окрім самого Stimulus.
Живе демо
Потягніть зону нижче в будь-який бік — під нею зʼявляться живі значення подій.
Зона жестів — тягніть у будь-який бік
Посилання всередині зони клік працює, а перетягування з нього — вже жест без переходу
data-swipe-ignore — жест звідси подій не надсилає. - dragStart
- -
- dragging
- -
- dragEnd
- -
- swipe
- -
- click
- -
Installation
With npm or any bundler:
npm install @sol-parts/sol-stimulus-components
With Symfony AssetMapper:
php bin/console importmap:require @sol-parts/sol-stimulus-components/swipe
Usage
Register the controller in your Stimulus application:
import { Application } from '@hotwired/stimulus';
import Swipe from '@sol-parts/sol-stimulus-components/swipe';
const app = Application.start();
app.register('swipe', Swipe);
Markup
Attach the controller to any element and listen to its events with standard Stimulus actions — this is how swipe composes with a gallery, a slideshow or your own controller:
<div data-controller="swipe"
data-action="swipe:swipeLeft->gallery#next swipe:swipeRight->gallery#prev">
…
</div>
Events
Every event carries { clientX, clientY, distanceX, distanceY, pointerType, threshold } in detail. pointerType is mouse or touch. A gesture longer than the configured threshold counts as a swipe; a shorter one — as a click.
| Event | Fired when |
|---|---|
swipe:swipeLeft / swipe:swipeRight / swipe:swipeUp / swipe:swipeDown | travel exceeded the threshold, dominant axis picked |
swipe:dragStart | gesture started |
swipe:dragging | pointer moved (throttled via requestAnimationFrame) |
swipe:dragEnd | gesture ended — detail.swipe names the recognised direction, or is null; canceled gestures also carry detail.canceled=true |
swipe:click | gesture ended without a swipe |
swipe:dragEnd fires for every finished gesture, so anything moved while swipe:dragging was firing has a single place to settle, without re-deriving the threshold on the listening side.
Set data-swipe-threshold-value to change the default 30 pixel threshold.
Links inside the swipe area
A mouse drag that starts on a link suppresses the native click for the duration of the gesture; when the gesture turns out to be a plain click, the link is re-triggered. Links inside the area keep working, while real swipes never navigate away.
On touch, none of that happens: the synthesised mouse events a browser sends after a tap are ignored, so the link is never touched and the browser's own click opens it. Only a touch gesture that really travels turns into a swipe.
Opting out: data-swipe-ignore
Buttons, form controls and editable content are ignored automatically. Any other descendant can opt out with data-swipe-ignore. Gestures starting in ignored content dispatch neither drag/swipe events nor swipe:click.
Nested swipe controllers are isolated: only the closest controller handles the gesture.