vue3-touch-events - npm Package Compare versions

Comparing version 3.1.1 to 4.0.0

index.js

@@ -66,5 +66,5 @@ /**
 
-            $this.touchStarted = true;
+            $this.touchStarted = true; // always true while the element is being PRESSED
 
-            $this.touchMoved = false;
+            $this.touchMoved = false; // true only when the element is PRESSED and DRAGGED a bit
             $this.swipeOutBounded = false;
@@ -75,3 +75,3 @@
 
-            $this.currentX = 0;
+            $this.currentX = 0; // always updated with the last mouse X/Y while over the element
             $this.currentY = 0;
@@ -84,6 +84,6 @@
                 $this.touchHoldTimer = null;
-                triggerEvent(event, $el, 'touchhold');
+                triggerEvent(event, $el, 'hold');
             }, $this.options.touchHoldTolerance);
 
-            triggerEvent(event, this, 'start');
+            triggerEvent(event, this, 'press');
         }
@@ -93,5 +93,10 @@
             var $this = this.$$touchObj;
+			
+			var curX = touchX(event);
+			var curY = touchY(event);
 
-            $this.currentX = touchX(event);
-            $this.currentY = touchY(event);
+			var movedAgain = ($this.currentX != curX) || ($this.currentY != curY);
+			
+            $this.currentX = curX;
+            $this.currentY = curY;
 
@@ -102,7 +107,7 @@ if (!$this.touchMoved) {
                 $this.touchMoved = Math.abs($this.startX - $this.currentX) > tapTolerance ||
-                    Math.abs($this.startY - $this.currentY) > tapTolerance;
+								   Math.abs($this.startY - $this.currentY) > tapTolerance;
 
                 if($this.touchMoved){
                     cancelTouchHoldTimer($this);
-                    triggerEvent(event, this, 'moved');
+                    triggerEvent(event, this, 'drag.once');
                 }
@@ -117,4 +122,4 @@
 
-            if($this.touchMoved){
-                triggerEvent(event, this, 'moving');
+            if($this.touchStarted && $this.touchMoved && movedAgain){
+                triggerEvent(event, this, 'drag');
             }
@@ -154,3 +159,3 @@ }
             // Fix #33, Trigger `end` event when touch stopped
-            triggerEvent(event, this, 'end');
+            triggerEvent(event, this, 'release');
 
@@ -165,3 +170,3 @@ if (!$this.touchMoved) {
 
-                } else if ($this.callbacks.touchhold && touchholdEnd) {
+                } else if ($this.callbacks.hold && touchholdEnd) {
                     if (event.cancelable) {
@@ -212,4 +217,4 @@ event.preventDefault();
             // get the callback list
-            var callbacks = $this.callbacks[eventType] || [];
-            if (callbacks.length === 0) {
+            var callbacks = $this.callbacks[eventType] || null;
+            if (callbacks == null || callbacks.length === 0) {
                 return null;
@@ -303,6 +308,6 @@ }
 
-                    case 'start':
-                    case 'moving':
+                    case 'press':
+                    case 'drag':
                         if (binding.modifiers.disablePassive) {
-                            // change the passive option for the moving event if disablePassive modifier exists
+                            // change the passive option for the `drag` event if disablePassive modifier exists
                             passiveOpt = false;
@@ -309,0 +314,0 @@ }

package.json

 {
   "name": "vue3-touch-events",
-  "version": "3.1.1",
+  "version": "4.0.0",
   "description": "Simple touch events support for vue.js 3",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

 # vue3-touch-events [![](https://img.shields.io/npm/v/vue3-touch-events.svg)](https://www.npmjs.com/package/vue3-touch-events)
 
-Enable tap / swipe / touch / hold / mouse down / mouse up events for vue.js 3.x.
+**Enable tap, swipe, touch, hold, mouse down, mouse up events on any HTML DOM Element in vue.js 3.x.**
 
-> Note: This is for **vue.js 3.x** only.
+The easiest way to make your interactive vue.js content mobile-friendly. When you add `v-touch` events to your elements, it works on desktop and mobile using a fully declarative syntax. Unlike other libraries, you do not need to add any special code to your components to make this work. You simply have to register the library globally and it enables new events throughout your application.
 
+Released under the permissive MIT License.
+
 Features:
 
-- Common touch events, such as `tap`, `swipe`, `touchhold` ([more](#Bindings))
-- All events support mouse and touch screen at same time
-- Optimized touch effects with `touchClass` option and `v-touch-class` directive
-- Binding multiple touch events on one DOM element
-- Customizable events with native-likely events handler
-- Allow splitting configurations for different DOM elements by `v-touch-options` directive
+- Declarative syntax for common touch events, such as `tap`, `swipe`, `touchhold` ([more](#Events))
+- All events support desktop (mouse) and mobile devices (touch screen) with the same syntax
+- Automatically add styling on hover and tap using `v-touch-class` directive
+- Bind multiple touch events on one DOM element
+- Customizable events with native-like events handler
+- Global configuration that applies to all events in the application
+- Ability to override global configuration on any element using `v-touch-options` directive
+- Bindings for TypeScript included and also works in pure-JavaScript projects
 
+Version:
+
+> Note: This library is for **vue.js 3.x** only. For **vue.js 2.x** see the [older library](https://github.com/jerrybendy/vue-touch-events).
+
 Credits:
@@ -21,16 +29,23 @@
 
-## Install
 
-To install with npm or yarn, use
 
+
+## Installation
+
+To install with npm:
+
 ```shell
-npm i -S vue3-touch-events
+npm install vue3-touch-events
+```
 
-// or
+To install with yarn:
 
+```shell
 yarn add vue3-touch-events
 ```
 
-## Usage
+### TypeScript
 
+You need to register this plugin with vue.js in your main application file:
+
 ```js
@@ -43,5 +58,20 @@ import Vue from "vue";
 
-In your `.vue` file:
+### JavaScript
 
+You need to include the [UMD script](https://raw.githubusercontent.com/robinrodricks/vue3-touch-events/master/index.js) of this plugin and you do not need to register this plugin with vue.js.
+
 ```html
+<script src="libs/vue.js"></script>
+<script src="libs/vue3-touch-events.js"></script>
+```
+
+
+
+## Examples
+
+In your `.vue` component files, use the `v-touch` directive add touch events to elements.
+
+Specify the event using the first argument, for example `v-touch:tap` or `v-touch:swipe`.
+
+```html
 <!-- bind a tap event -->
@@ -57,3 +87,3 @@ <span v-touch:tap="touchHandler">Tap Me</span>
 <!-- only when swipe left can trigger the callback -->
-<span v-touch:swipe.left="swipeHandler">Swipe Here</span>
+<span v-touch:swipe.left="swipeHandler">Swipe Left Here</span>
 
@@ -64,119 +94,147 @@ <!-- bind a long tap event -->
 <!-- bind a start and end event -->
-<span v-touch:start="startHandler" v-touch:end="endHandler"
-  >Down,start/Up,end Event</span
->
+<span v-touch:press="startHandler" v-touch:release="endHandler">Press and Release Events</span>
 
 <!-- bind a move and moving event -->
-<span v-touch:moved="movedHandler"
-  >Triggered once when starting to move and tapTolerance is exceeded</span
->
-<span v-touch:moving="movingHandler">Continuously triggering Event</span>
+<span v-touch:drag.once="movedHandler">Triggered once when starting to move and tapTolerance is exceeded</span>
+<span v-touch:drag="movingHandler">Continuously triggered while dragging</span>
 
 <!-- touch and hold -->
-<span v-touch:touchhold="touchHoldHandler"
-  >Touch and hold on the screen for a while</span
->
+<span v-touch:hold="touchHoldHandler">Touch and hold on the screen for a while</span>
 
 <!-- you can even mix multiple events -->
-<span
-  v-touch:tap="tapHandler"
-  v-touch:longtap="longtapHandler"
-  v-touch:swipe.left="swipeLeftHandler"
-  v-touch:start="startHandler"
-  v-touch:end="endHandler"
-  v-touch:swipe.right="swipeRightHandler"
-  >Mix Multiple Events</span
->
+<span v-touch:tap="tapHandler" v-touch:longtap="longtapHandler" v-touch:swipe.left="swipeLeftHandler" v-touch:press="startHandler" v-touch:release="endHandler" v-touch:swipe.right="swipeRightHandler">Mix Multiple Events</span>
 
 <!-- using different options for specified element -->
-<span
-  v-touch:tap="tapHandler"
-  v-touch-options="{touchClass: 'active', swipeTolerance: 80, touchHoldTolerance: 300}"
-  >Different options</span
->
+<span v-touch:tap="tapHandler" v-touch-options="{touchClass: 'active', swipeTolerance: 80, touchHoldTolerance: 300}">Different options</span>
 
 <!-- customize touch effects by CSS class -->
-<span v-touch:tap="tapHandler" v-touch-class="active"
-  >Customize touch class</span
->
+<span v-touch:tap="tapHandler" v-touch-class="active">Customize touch class</span>
 <!-- or -->
-<span v-touch:tap="tapHandler" v-touch-options="{touchClass: 'active'}"
-  >Customize touch class</span
->
+<span v-touch:tap="tapHandler" v-touch-options="{touchClass: 'active'}">Customize touch class</span>
 ```
 
-If you use vue and this plugin in UMD way (in a script tag) , this plugin is auto used. So it's not necessary to wirte `Vue.use(Vue3TouchEvents)`.
 
+
+## Usage
+
+### Simple callback
+
+If you simply want to execute a callback function on a `v-touch` event, use this pattern:
+
 ```html
-<script src="path/to/vue.js"></script>
-<script src="path/to/vue-touch-events.js"></script>
+<div v-touch:tap="onTapItem">Button</div>
 ```
 
-## APIs
+```js
+methods: {
+	onTapItem() {
+		console.log("Tapped!");
+	},
+},
+```
 
-### Global configuration (optional)
+### Passing parameters to the event handler
 
+If you want to add extra parameters to your `v-touch` event handler, you need to return a delegate in the event handler. You can pass as many attributes as you need.
+
+```html
+<div v-for="(item, i) in items">
+	<div v-touch:swipe="onSwipeItem(item, i)">Button</div>
+</div>
+```
+
 ```js
-Vue.use(Vue3TouchEvents, {
-  disableClick: false,
-  touchClass: "",
-  tapTolerance: 10,
-  touchHoldTolerance: 400,
-  swipeTolerance: 30,
-  longTapTimeInterval: 400,
-});
+methods: {
+	onSwipeItem(item, i) {
+		return function (direction, event) {
+			console.log("Swiped item ", i, ": ", item, " in direction ", direction);
+		};
+	},
+},
 ```
 
-- `disableClick` default `false`. Use touch event only, will not trigger click event.
 
-  You should keep this value default if you use your website on both mobile and PC.
 
-  If your website uses on mobile only, it's a good choice to set this value to `true` to get a better user experience, and it can resolve some touch pass-through issue.
 
-- `touchClass` default: `''`. Add an extra CSS class when touch start, and remove it when touch end.
+## Events
 
-  This is a global config, and you can use `v-touch-class` directive to overwrite this setting in a single component.
+List of all supported events are given below.
 
-- `tapTolerance` default `10`. The tolerance to ensure whether the tap event effective or not.
+| <div style="width:170px">Event</div>                      | Behaviour                                                |
+| ---------------------------- | ----------------------------------------------------- |
+|  `v-touch`<br> `v-touch:tap` | **Desktop:** Triggered when the user clicks on the element (press and release). <br> **Mobile:** Triggered when the user taps on the element (tap and release)      |
+| `v-touch:longtap` | **Desktop:** Triggered when the user holds on the element for `longTapTimeInterval` MS and then releases it (press and release). <br> **Mobile:** Triggered when the user taps and holds on the element for `longTapTimeInterval` MS and then releases it (tap and release)      |
+| `v-touch:swipe`              | Triggered when the user drags on the element (swipe). <br> It will detect the direction of the swipe and send it to your callback. <br> First argument of the callback must be `direction` attribute, which can be `left`, `right`, `top` or `bottom`. <br> Example callback: `onSwipe(direction){ ... }` |
+| `v-touch:swipe.left` <br>`v-touch:swipe.right` <br>`v-touch:swipe.top` <br>`v-touch:swipe.bottom` <br> | Triggered when the user drags on the element in a specific direction (directional swipe).
+| `v-touch:hold`              | Triggered when the user holds the mouse button down for `touchHoldTolerance` MS while over the element (press and hold). <br> This will be triggered before your finger is released, similar to what native mobile apps do.    |
+| `v-touch:press`              | **Desktop:** Triggered when the user presses the element (mouse down). <br> **Mobile:** Triggered when the user taps the element without releasing.    |
+| `v-touch:drag.once`              | Triggered when the user presses and drags the element. <br> Only fired once, the moment the user first drags on the element.   |
+| `v-touch:drag`             | Triggered when the user presses and drags the element. <br> Fired every time the mouse moves while dragging the element.   |
+| `v-touch:release`                | **Desktop:** Triggered when the user releases the element (mouse up). <br> **Mobile:** Triggered when the user taps and releases the element.  |
 
-- `touchHoldTolerance` default `400` in millisecond. The timeout for a `touchhold` event.
 
-- `swipeTolerance` default `30`. The tolerance to ensure whether the swipe event effective or not.
 
-- `longTapTimeInterval` default `400` in millisecond. The minimum time interval to detect whether long tap event effective or not.
+### Migration from Vue 2.x
 
-### Directives
+Some events have been renamed from the vue 2.x version of this library, in order to expose a cleaner, more consistant and more descriptive naming scheme.
 
-#### v-touch
+| Old event name               | New event name      |
+| ---------------------------- | ------------------- |
+| `v-touch:touchhold`          | `v-touch:hold`      |
+| `v-touch:start`              | `v-touch:press`     |
+| `v-touch:end`                | `v-touch:release`   |
+| `v-touch:moved`              | `v-touch:drag.once` |
+| `v-touch:moving`             | `v-touch:drag`      |
 
-Bind the `v-touch` directive to components which you want to enable touch events.
 
-`v-touch` accepts an argument to tell it which event you want to bind.
 
-```html
-<span v-touch:tap="tapHandler">Tap</span>
-```
+## Options
 
-The first argument of the `v-swipe` callback is the direction of swipe event. It could be `left`, `right`, `top` or `bottom`.
+These additional directives can be added to each element.
 
-`v-swipe` can accept extra modifiers. It means you can bind events only for specify direction.
+### v-touch-options
 
-```js
-export default {
-  methods: {
-    swipeHandler(direction) {
-      console.log(direction); // May be left / right / top / bottom
-    },
-  },
-};
-```
+`v-touch-options` directive allows you set a different configuration for a specified component. It will override global configurations.
 
-### v-touch-options `(v2.2.0)`
+### v-touch-class
 
-`v-touch-options` directive allows you set a different configuration for a specified component. It will override global configurations.
+`v-touch-class` directive allows you automatically add a class when the element is rolled over (desktop) or tapped (mobile). It overrides the class specified in the global config option `touchClass`.
 
-#### v-touch-class
+- By default the `touchClass` is added when the element is pressed (`mousedown`), and removed when the element is released (`mouseup`).
+- If desktop events are enabled (`disableClick: false`), then the `touchClass` is added on roll over (`mouseenter`) and roll out (`mouseleave`) as well.
+- You can use this instead of `:active` and `:hover` pseudo classes, as it works on both desktop and mobile
 
-`v-touch-class` directive allows you set an extra class on your components. If you already have a global config `touchClass`, this value will **overwrite** it.
+Behaviour:
 
+<table>
+	<tr>
+		<th>Device</th>
+		<th>Event name</th>
+		<th>Effect</th>
+		<th>Condition</th>
+	</tr>
+	<tr>
+		<td rowspan="2">Desktop only</td>
+		<td>Mouse enter (roll over)</td>
+		<td>`touchClass` added</td>
+		<td>desktop events must be enabled</td>
+	</tr>
+	<tr>
+		<td>Mouse leave (roll out)</td>
+		<td>`touchClass` removed</td>
+		<td>desktop events must be enabled</td>
+	</tr>
+	<tr>
+		<td rowspan="2">Mobile only</td>
+		<td>Mouse down (press)</td>
+		<td>`touchClass` added</td>
+		<td></td>
+	</tr>
+	<tr>
+		<td>Mouse up (release)</td>
+		<td>`touchClass` removed</td>
+		<td></td>
+	</tr>
+</table>
+
 For example:
@@ -188,6 +246,4 @@
 
-Now, when you start to touch, it will add an extra `active` class automatically. And remove it when touch end.
+Now, when you press the element, it will add an extra `active` class automatically, and when you release the element the class will be removed.
 
-If your setting of `disableClick` is `false` (it's default), it will bind `mouseenter` and `mouseleave` events, too.
-
 So that you can use this feature to instead of `:active` and `:hover` pseudo class, for a better user experience.
@@ -199,3 +255,3 @@
 span:hover {
-  background: green;
+	background: green;
 }
@@ -205,87 +261,36 @@
 span.active {
-  background: green;
+	background: green;
 }
 ```
 
-### Bindings
+## Global configuration
 
-#### v-touch:tap / v-touch
+```js
+Vue.use(Vue3TouchEvents, {
+	disableClick: false,
+	touchClass: "",
+	tapTolerance: 10,
+	touchHoldTolerance: 400,
+	swipeTolerance: 30,
+	longTapTimeInterval: 400,
+});
+```
 
-`tap` is the default event type of `v-touch`. It will be trigger when tap on the screen or click the mouse.
+- `disableClick` - Whether to disable desktop events. **Default:** `false`.
 
-#### v-touch:swipe
+  Keep the default value or `false` if your application is used on desktop and mobile devices.
 
-`swipe` means touch on the screen and move in a direction. The direction could be `top`,`bottom`,`left` or `right`.
+  If your application is only for mobile use, set this to `true` to get a better user experience, because it can resolve some touch pass-through issues encountered on mobile devices.
 
-#### v-touch:longtap
+- `touchClass` - Which CSS class to add while an element is rolled over (desktop) or tapped (mobile). **Default:** `''`
 
-> `longtap` will be deprecated in next major version. Please use `touchhold` insead. If you still want to use this feature, please let me know.
+  This is a global config, and you can use `v-touch-class` directive to override this setting for a single element.
 
-`longtap` means touch on the screen and hold for a while. It will be triggered when you release your finger. (It's not normal when we use touch devices, so it's a good choice to use `touchhold` instaed)
+- `tapTolerance` in pixels - How many pixels the user must drag on the element for it to register as a `tap` event. **Default:** `10` pixels.
 
-#### v-touch:touchhold `(v2.1.0)`
+- `touchHoldTolerance` in milliseconds - The timeout for a `touchhold` event. **Default:**  `400` MS
 
-`touchhold` will be triggered when touch on the screen and hold for `touchHoldTolerance` milliseconds. This will be triggered before your finger released, as what native APP does.
+- `swipeTolerance` in pixels - How many pixels the user must drag on the element for it to register as a `swipe` event. **Default:**  `30` pixels.
 
-#### v-touch:start / v-touch:end / v-touch:moving
+- `longTapTimeInterval` in milliseconds - The minimum time interval to detect whether long tap event effective or not.  **Default:**  `400` MS.
 
-- `start` is same as `touchstart` or `mousedown`.
-- `end` is same as `touchend` or `mouseup`.
-- `moving` is same as `touchmovoe` or `mousemove`.
-
-These three events are like native DOM events. You can use these events to custom behaviors which this library doesn't support yet.
-
-### Modifiers
-
-#### left, right, top, bottom
-
-This four modifiers are for `v-touch:swipe` only, to specify which direction you want to bind events to.
-
-#### self
-
-Same as `v-on:click.self`, only trigger events when the event target is the `currentTarget`.
-
-#### stop
-
-Same as `v-on:click.stop`, stops event propagation.
-
-#### prevent
-
-Same as `v-on:click.prevent`, prevents default event handler from firing.
-
-#### disablePassive `(v2.3.0)`
-
-`{passive: true}` is set for touch event listeners if your browser supports `passive`. This is good for user experience. If this is not what you want, you can use `disablePassive` modifier to prevent this behavior.
-
-## Others
-
-### How to add extra parameters
-
-As mentioned by [#3](https://github.com/jerrybendy/vue-touch-events/issues/3), if you want to add extra
-parameters for `v-touch`, you can't do that like `v-on`. The hack is that you can let your method returns
-a `function` and handle the extra parameters in the returned function.
-
-```html
-<div v-touch:swipe="myMethod('myOtherParam')">Swipe</div>
-```
-
-```js
-export default {
-  methods: {
-    myMethod(param) {
-      return function (direction, event) {
-        console.log(direction, param);
-        // do something ~
-      };
-    },
-  },
-};
-```
-
-## Change History
-
-[Look at here](https://github.com/jerrybendy/vue-touch-events/releases)
-
-## LICENSE
-
-MIT License

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

27284

increased by12.1%

Lines of code

313

increased by0.97%

Number of lines in readme file

290

increased by1.75%

No dependency changes