Vue触控事件插件

使 Vue.js 2.x 能够使用轻击、滑动、长按等触控事件。

特性：

• 包括常见触控事件如 tap、swipe、touchhold （更多见[Bindings]部分）
• 所有事件同时支持鼠标和触摸屏操作
• 使用 touchClass 选项和 v-touch-class 指令优化触控效果
• 可在一个DOM元素上绑定多个触控事件
• 支持自定义事件处理器，类似原生事件处理
• 允许通过 v-touch-options 指令为不同DOM元素配置独立设置
• 指令名称可定制，避免命名空间冲突

注意：此库仅适用于 Vue.js 2.x 。若需适用 Vue.js 3.x，请查看这个库。

安装

通过 npm 或 yarn 安装：

npm install -S vue2-touch-events

# 或者

yarn add vue2-touch-events

使用

在你的 .vue 文件中：

import Vue from 'vue';
import Vue2TouchEvents from 'vue2-touch-events';

Vue.use(Vue2TouchEvents);

模板示例：

<!-- 绑定轻击事件 -->
<span v-touch:tap="handleTap">轻击我</span>

<!-- 轻击是默认事件，可以省略 -->
<span v-touch="handleTap">轻击我</span>

<!-- 绑定滑动事件，不指定方向 -->
<span v-touch:swipe="handleSwipe">在这里滑动</span>

<!-- 只有向左滑动时触发回调 -->
<span v-touch:swipe.left="handleSwipe">向左滑动</span>

<!-- 绑定长按事件 -->
<span v-touch:longtap="handleLongTap">长按事件</span>

<!-- 绑定开始和结束事件 -->
<span v-touch:start="handleStart" v-touch:end="handleEnd">按下的开始/抬起的结束事件</span>

<!-- 绑定移动开始和移动过程中事件 -->
<span v-touch:moved="handleMoved">移动开始并超出触碰容忍度后触发一次</span>
<span v-touch:moving="handleMoving">持续触发事件</span>

<!-- 触摸并保持一段时间 -->
<span v-touch:touchhold="handleTouchHold">屏幕保持一会儿</span>

<!-- 复合多种事件 -->
<span v-touch:tap="handleTap"
      v-touch:longtap="handleLongTap"
      v-touch:swipe.left="handleSwipeLeft"
      v-touch:start="handleStart" 
      v-touch:end="handleEnd"
      v-touch:swipe.right="handleSwipeRight">组合事件</span>

<!-- 针对特定元素使用不同的选项 -->
<span v-touch:tap="handleTap"
      v-touch-options="{touchClass: 'active', swipeTolerance: 80, touchHoldTolerance: 300}">不同选项</span>

<!-- 通过CSS类自定义触控效果 -->
<span v-touch:tap="handleTap" v-touch-class="active">自定义触控类</span>
<!-- 或 -->
<span v-touch:tap="handleTap" v-touch-options="{touchClass: 'active'}">自定义触控类</span>

<!-- 更改指令名称以避免命名空间冲突 -->
<span v-kiss:tap="handleTap">命名空间改为'kiss'</span>

如果你直接用 UMD 方式（通过脚本标签）使用 Vue 和此插件，插件会自动安装，无需写 Vue.use(Vue2TouchEvents)。

<script src="path/to/vue.js"></script>
<script src="path/to/vue-touch-events.js"></script>

API

全局配置（可选）

Vue.use(Vue2TouchEvents, {
    disableClick: false,
    touchClass: '',
    tapTolerance: 10,
    touchHoldTolerance: 400,
    swipeTolerance: 30,
    longTapTimeInterval: 400,
    namespace: 'touch'
});

• disableClick: 默认 false，仅使用触控事件，不会触发点击事件。 如果你的网站同时用于手机和PC，建议保留默认值。 若仅针对移动端，设置为 true 可提升用户体验，并解决某些触控穿透问题。

• touchClass: 默认为空字符串。触控开始时添加额外的CSS类，并在触控结束时移除。 这是一个全局配置，但你可以通过 v-touch-class 指令在单个组件中覆盖这一设置。

• 其他配置项分别控制触控事件的宽容距离、长按时长、滑动手势的识别阈值以及命名空间设定等。

指令

v-touch

将 v-touch 指令应用于需要启用触控事件的组件。

v-touch 接受参数来指定要绑定的事件类型。

<span v-touch:tap="handleTap">轻击</span>

v-swipe 的回调函数第一个参数表示滑动的方向（左、右、上、下）。

通过添加修饰符到 v-swipe，可以仅对特定方向的滑动绑定事件。

v-touch-options (自 v2.2.0)

v-touch-options 指令允许你为指定的组件设置不同的配置，它会覆盖全局配置。

v-touch-class

v-touch-class 指令允许你在组件上设置一个额外的类名。如果你已经有了全局配置 touchClass，这个值将会覆盖它。

例如，当触控开始时自动添加 active 类，结束时移除。

如果 disableClick 设置为默认的 false，它也会绑定 mouseenter 和 mouseleave 事件，以便能像使用:active和:hover伪类一样，提供更好的用户体验。

/* 原始方式 */
span:active, span:hover {
  background: green;
}

/* 现在的方式 */
span.active {
  background: green;
}

Bindings（绑定事件）

• v-touch:tap / v-touch “tap”是 v-touch 的默认事件类型，手指轻触屏幕或鼠标点击时触发。

• v-touch:swipe 表示手指在屏幕上滑动并朝特定方向移动（上、下、左、右）。

• v-touch:longtap（已废弃，推荐使用touchhold） 指的是手指接触屏幕并保持一段时间后松开。考虑到触摸设备的一般交互习惯，推荐使用 touchhold。

• v-touch:touchhold（自 v2.1.0） 当手指接触屏幕保持 touchHoldTolerance 毫秒后触发，模仿原生应用行为，在手指离开之前触发。

• v-touch:start / v-touch:end / v-touch:moving 分别对应原生的 touchstart/mousedown、touchend/mouseup、touchmove/mousemove，可用于自定义插件未涵盖的行为。

修饰符

left, right, top, bottom

这四个修饰符专用于 v-touch:swipe，用来指定事件绑定的方向。

self

与 v-on:click.self 相同，只有当事件目标是 currentTarget 时才会触发事件。

stop

与 v-on:click.stop 相同，阻止事件冒泡。

prevent

与 v-on:click.prevent 相同，防止默认事件处理器执行。

disablePassive (v2.3.0)

如果浏览器支持 passive，触摸事件监听器会设置 {passive: true}，以优化用户体验。若不希望如此，你可以使用 disablePassive 修饰符来阻止这一行为。

其他

添加额外参数

如 #3 中提到，如果你想给 v-touch 添加额外参数，不能像 v-on 那样直接操作。一个变通方法是让方法返回一个 函数，在返回的函数中处理额外的参数。

<div v-touch:swipe="myMethod('myOtherParam')">滑动</div>