重磅！Vue3 手势工具正式发布！免费使用！

vue3-touch-events 是 Vue3 专用触控事件库，可在任意 HTML 元素上启用 tap、swipe、touch、hold、drag、zoom 等事件，一套语法同时支持 PC 鼠标与移动端触屏，全局注册后全项目可用，无需改造组件。基于 MIT 协议开源，仅支持 Vue3。

核心功能

声明式 v-touch 指令，支持点击、滑动、长按、拖拽、缩放等常用事件
同一元素可绑定多个触控事件，同时兼容桌面端与移动端
支持 v-touch-class 自动添加交互样式类，替代 hover/active 伪类
所有事件支持节流配置，避免高频触发导致页面卡顿
支持全局统一配置，也可通过 v-touch-options 对单个元素单独覆盖
内置 TypeScript 类型，JS / TS 项目均可使用

安装

npm：npm install vue3-touch-events
bun：bun add vue3-touch-events
yarn：yarn add vue3-touch-events

注册方式

普通 Vue3 项目

javascript 复制代码

import Vue3TouchEvents from 'vue3-touch-events'  
app.use(Vue3TouchEvents, {  
  disableClick: false  
})

TypeScript + Vue3.4+

typescript 复制代码

import Vue3TouchEvents, { type Vue3TouchEventsOptions } from 'vue3-touch-events'  
app.use<Vue3TouchEventsOptions>(Vue3TouchEvents, {  
  disableClick: false  
})

Nuxt 3

在 plugins/ 目录新建文件：

javascript 复制代码

import Vue3TouchEvents from 'vue3-touch-events'  
export default defineNuxtPlugin((nuxtApp) => {  
  nuxtApp.vueApp.use(Vue3TouchEvents)  
})

常用事件（单行分点）

v-touch:tap / v-touch：PC 点击、移动端轻触，松开后触发
v-touch:longtap：长按默认 400ms 后松开触发
v-touch:hold：按住达到指定时长立即触发，无需松开
v-touch:press：按下时触发（mousedown / touchstart）
v-touch:release：松开时触发（mouseup / touchend）
v-touch:swipe：任意方向滑动，回调返回方向 left/right/top/bottom
v-touch:swipe.left：仅监听向左滑动
v-touch:swipe.right：仅监听向右滑动
v-touch:swipe.top：仅监听向上滑动
v-touch:swipe.bottom：仅监听向下滑动
v-touch:drag.once：开始拖拽时只触发一次
v-touch:drag：拖拽过程中持续触发，自带节流
v-touch:zoom：移动端双指缩放时持续触发，返回缩放比例
v-touch:zoom.in：双指捏合放大时触发
v-touch:zoom.out：双指张开缩小时触发
v-touch:rollover：仅 PC 鼠标悬浮触发，自带节流

常用指令

v-touch-options：为单个元素单独配置，覆盖全局设置
v-touch-class：元素按下/悬浮时自动加 CSS 类，替代 :hover/:active

事件传参

直接传参需要返回闭包函数：

ini 复制代码

<div v-touch:swipe="onSwipeItem(item, i)"></div>

javascript 复制代码

onSwipeItem(item, i) {  
  return (direction, event) => { /* 逻辑 */ }  
}

常用配置项（单行分点）

touchHoldTolerance：hold 触发延迟，默认 400ms
longTapTimeInterval：longtap 长按时长，默认 400ms
rollOverFrequency：悬浮事件触发频率，默认 100ms
swipeTolerance：滑动有效像素，默认 100px
swipeConeSize：滑动识别角度范围 0~1，默认 0.75
tapTolerance：区分拖拽与点击的像素值，默认 10px
dragFrequency：拖拽事件频率，默认 10ms
dragOutside：鼠标移出元素是否继续触发 drag，默认 false
zoomFrequency：缩放事件频率，默认 10ms
zoomDistance：缩放触发距离，默认 10px
zoomInOutDistance：放大缩小触发距离，默认 100px
disableClick：是否禁用 PC 点击事件，移动端专用建议设为 true
touchClass：全局默认触控样式类
namespace：自定义指令前缀，默认 touch

实用优化建议

拖拽/滑动卡顿：将 dragFrequency 或 rollOverFrequency 设为 16 适配 60 帧
移动端点击穿透：开启 disableClick: true
滑动识别不灵敏：调大 swipeTolerance 或 swipeConeSize
多端样式统一：用 v-touch-class 替代 CSS 伪类 :active / :hover