
最近在做一个移动端优先的管理后台产品经理提了个听起来很简单的需求列表里的每条记录要支持长按呼出操作菜单手机上手指按住约 600ms 出菜单桌面上鼠标按住也要有同样的效果。等我真的打开编辑器准备动手时才发现长按在 Web 端根本不是“按住不动”这么简单——click 事件给不了按压时长的信息触摸事件和鼠标事件的行为又完全不同稍不注意就会出现要么长按失效、要么单击也触发的诡异现象。最后我用 Vue3 TypeScript 实现了一个v-longPress自定义指令把移动端和 PC 端的差异全部收敛进一个指令里。这里记录的就是我从需求拆解到最终封装的完整过程希望给准备做长按交互的 Vue3 开发同学一些参考。1. 长按的真正难点不在“按住”而在“如何区分单击与长按”1.1 看着简单的需求背后全是边界情况我最初以为长按就是监听一次“按下”事件然后开个定时器到点就触发回调。但真正梳理之后发现产品经理口中的“长按”至少包含这些语义按下的时间要超过一个阈值比如 600ms按住期间手指或鼠标不能移动太多否则用户可能是在滚动列表或者拖拽元素长按期间不能触发系统默认行为比如移动端长按图片会弹出保存菜单长按结束后不能紧接着又触发一次 click如果有短按需求比如短按时打开详情页、长按时呼出菜单两者不能互相干扰。这些需求单独看都不难难在它们全部要在一个交互里同时成立。如果你只在某个组件里临时用setTimeout处理那每次遇到长按场景都要重新写一遍而且大概率会漏掉其中一两个边界情况。我在那个项目里一开始就是直接在列表组件里写的结果换一个页面要用长按时复制过来一堆监听代码还得根据新页面的滚动容器重新调参非常痛苦。1.2 click 不是长按的触发器很多人可能第一反应是click 能不能判断长按答案是不能。click 事件在语义上只是“按下后抬起”的确认信号它不暴露按下持续时间。你用Date.now()在 click 里减一下“按下时间”确实能算出一个时长但问题是如果用户按住 300ms 后松手click 会触发但 300ms 不满足长按阈值如果用户按住 800ms 后松手click 也会触发但你拿不到“从按下到抬起”的完整时间线除非你在 mousedown 或 touchstart 时就记录时间click 在移动端还有一层历史包袱早期移动端浏览器为双击缩放预留了约 300ms 延迟现代浏览器虽然通过 viewport 设置消除了这个问题但移动端触摸结束后合成 click 的行为依然存在。所以真正要做长按必须在 mousedown / touchstart 这一层就开始介入自己维护计时器和位移判定。click 只能作为“长按结束后的一个待处理信号”来看待。1.3 为什么用自定义指令而不是组件或工具函数我当时其实考虑过三种方案写一个useLongPress组合式函数、封装一个LongPress组件、写一个v-longPress指令。组合式函数适合在script setup里手动绑定事件比如const { onPress } useLongPress(elRef, options)但这样的调用方式还是偏命令式模板里的可读性一般而且团队成员在 DOM 上手动绑定事件容易忘记解绑。组件方案会在模板里多包一层 DOM比如LongPress triggeropenMenudiv内容/div/LongPress虽然也能做但多出的标签层级在某些布局场景下会带来意外的样式影响。指令方案最贴近模板语义v-longPresshandler写在哪个元素上长按就作用于哪个元素不引入额外 DOM也不需要手动管理监听器Vue 的生命周期钩子天然对齐了事件绑定和解绑。最终我选了自定义指令。对于一个需要跨页面复用的交互能力指令是 Vue3 里听起来最“重”、实际上最轻的封装方式。2. 移动端与 PC 端事件模型的差异决定你该监听什么2.1 触摸事件和鼠标事件的时间线对比移动端的触摸事件族是touchstart、touchmove、touchend、touchcancelPC 端的鼠标事件族是mousedown、mousemove、mouseup还有一个mouseleave用于处理鼠标移出元素的情况。两者的核心逻辑相似但有几个关键差异直接影响实现方案。能力点触摸事件移动端鼠标事件PC 端按下事件touchstart可拿到触点坐标mousedown可拿到光标坐标移动事件touchmove频繁触发mousemove频繁触发抬起事件touchendmouseup中断事件touchcancel如来电、系统弹窗mouseleave 或 window blur滚动冲突touchmove 默认会滚动页面鼠标滚轮滚动mousedown 拖拽会选中文本合成 click触摸结束后浏览器会补发 click按住并抬起后也会触发 click这里最麻烦的是移动端浏览器在手指抬起后会模拟生成一套鼠标事件包括 mousedown、mouseup 和 click。也就是说如果我在监听 touchstart 的同时也监听 mousedown那么在真机测试时会发现同一个手势触发了两套事件长按计时器会启动两次。这就是移动端和 PC 端“双端同时监听”最容易踩的坑。2.2 双端同时监听导致的重复执行问题触屏设备上用户手指按下时会先触发 touchstart过一段时间浏览器实现不同一般在几百毫秒内可能又合成一个 mousedown。如果我毫不在意地同时监听这两种事件看到的现象就是touchstart 触发开始计时浏览器合成 mousedown 触发又一次开始计时两个计时器都到点长按回调执行两次每次按下都出现两个定时器还可能在业务回调里打开两个菜单。解决思路很多最朴素也最稳妥的做法是当某次交互是从 touchstart 开始时设置一个“屏蔽合成鼠标事件”的时间窗口在这个时间窗口内忽略 mousedown。比如const suppressMouseUntil Date.now() 800然后 mousedown 的 handler 里判断if (Date.now() state.suppressMouseUntil) return这个方案不需要特判设备类型因为真正的 PC 端不会有 touchstart 触发自然也不会设置抑制时间mousedown 照常工作。而移动端因为 touchstart 已经接管了这次交互后续合成的 mousedown 会被无视。2.3 PointerEvent 能不能一统天下现代浏览器提供了一套 PointerEvent把鼠标、触摸、笔触统一成 pointerdown / pointermove / pointerup。理论上用 PointerEvent 一套事件就能同时覆盖移动端和 PC 端代码量也会更少。我在后期版本里确实写了一个 pointer 方案的实现代码比 touch mouse 双监听精简不少。但这套方案有两个前提条件目标浏览器需要完整支持 PointerEvent尤其是老一些的移动端 WebView兼容性不一定理想在触摸场景下必须配合 CSStouch-action的合理设置否则浏览器会在手势被识别为滚动时主动触发pointercancel长按会被系统打断。所以我最终交付的版本采用 touch mouse 双监听兼容性最稳。PointerEvent 的精简实现放在文末作为进阶方案供现代项目参考。3. v-longPress 指令实现与参数设计3.1 参数配置表一个长按指令最核心的参数可以收敛成以下几项每一项都对应前面提到的边界问题参数类型默认值作用delaynumber600长按触发阈值单位毫秒moveThresholdnumber10触发前允许手指或鼠标移动的像素数onStart(event) void空函数按下时回调可用于开始视觉反馈onTrigger(event) void空函数长按达成时回调核心业务逻辑onCancel(event) void空函数提前松手、位移超限或系统中断时回调allowClickAfterLongPressbooleanfalse长按结束后是否放行紧随的 click 事件delay默认 600ms 是业界比较常用的中间值iOS 系统菜单大约 500ms 触发Android 文本选择也差不多在这个量级。太短容易和单击误触混在一起太长又会让用户觉得“按了没反应”。moveThreshold默认 10px 也是一个经验值人的手指在屏幕上按压时本来就有轻微抖动10px 以内的位移可以忽略超过就判定为滚动或拖拽直接取消长按。3.2 完整指令代码直接上核心代码。这是基于 Vue3 TypeScript 的完整实现我用 WeakMap 保存每个 DOM 元素独立的按压状态避免多个元素共享一个定时器互相干扰。import type { Directive } from vue interface LongPressOptions { delay?: number moveThreshold?: number onStart?: (event: Event) void onTrigger?: (event: Event) void onCancel?: (event: Event) void allowClickAfterLongPress?: boolean } interface PressState { timer: number | null startX: number startY: number triggered: boolean suppressMouseUntil: number options: RequiredLongPressOptions } const DEFAULT_DELAY 600 const DEFAULT_MOVE_THRESHOLD 10 function noop(_event: Event) {} const pressStateMap new WeakMapHTMLElement, PressState() function getOptions(value?: LongPressOptions | ((event: Event) void)): RequiredLongPressOptions { const raw typeof value function ? { onTrigger: value } : value ?? {} return { delay: raw.delay ?? DEFAULT_DELAY, moveThreshold: raw.moveThreshold ?? DEFAULT_MOVE_THRESHOLD, onStart: raw.onStart ?? noop, onTrigger: raw.onTrigger ?? noop, onCancel: raw.onCancel ?? noop, allowClickAfterLongPress: raw.allowClickAfterLongPress ?? false, } } function getPressState(el: HTMLElement): PressState | undefined { return pressStateMap.get(el) } function clearTimer(state: PressState) { if (state.timer ! null) { window.clearTimeout(state.timer) state.timer null } } function handlePressStart(el: HTMLElement, event: Event, clientX: number, clientY: number) { const state getPressState(el) if (!state || state.timer ! null) return state.startX clientX state.startY clientY state.triggered false clearTimer(state) state.options.onStart(event) state.timer window.setTimeout(() { state.triggered true state.options.onTrigger(event) }, state.options.delay) } function handlePressMove(el: HTMLElement, event: Event, clientX: number, clientY: number) { const state getPressState(el) if (!state || state.timer null) return const dx Math.abs(clientX - state.startX) const dy Math.abs(clientY - state.startY) if (dx state.options.moveThreshold || dy state.options.moveThreshold) { clearTimer(state) state.options.onCancel(event) } } function handlePressEnd(el: HTMLElement, event: Event) { const state getPressState(el) if (!state) return clearTimer(state) if (!state.triggered) { state.options.onCancel(event) } } function handleTouchStart(this: HTMLElement, event: TouchEvent) { const touch event.touches[0] if (!touch) return const state getPressState(this) if (state) { state.suppressMouseUntil Date.now() 800 } handlePressStart(this, event, touch.clientX, touch.clientY) } function handleTouchMove(this: HTMLElement, event: TouchEvent) { const touch event.touches[0] if (!touch) return handlePressMove(this, event, touch.clientX, touch.clientY) } function handleTouchEnd(this: HTMLElement, event: TouchEvent) { handlePressEnd(this, event) } function handleTouchCancel(this: HTMLElement, event: TouchEvent) { handlePressEnd(this, event) } function handleMouseDown(this: HTMLElement, event: MouseEvent) { const state getPressState(this) if (!state) return if (Date.now() state.suppressMouseUntil) return handlePressStart(this, event, event.clientX, event.clientY) } function handleMouseMove(this: HTMLElement, event: MouseEvent) { handlePressMove(this, event, event.clientX, event.clientY) } function handleMouseUp(this: HTMLElement, event: MouseEvent) { handlePressEnd(this, event) } function handleClick(this: HTMLElement, event: Event) { const state getPressState(this) if (!state) return // 如果长按已经触发默认拦截这次 click避免业务回调执行两次 if (state.triggered) { if (!state.options.allowClickAfterLongPress) { event.preventDefault() event.stopPropagation() } state.triggered false } } export const vLongPress: DirectiveHTMLElement, LongPressOptions | ((event: Event) void) { mounted(el, binding) { const options getOptions(binding.value) const state: PressState { timer: null, startX: 0, startY: 0, triggered: false, suppressMouseUntil: 0, options, } pressStateMap.set(el, state) el.addEventListener(touchstart, handleTouchStart, { passive: true }) el.addEventListener(touchmove, handleTouchMove, { passive: true }) el.addEventListener(touchend, handleTouchEnd) el.addEventListener(touchcancel, handleTouchCancel) el.addEventListener(mousedown, handleMouseDown) el.addEventListener(mousemove, handleMouseMove) el.addEventListener(mouseup, handleMouseUp) el.addEventListener(mouseleave, handleMouseUp) el.addEventListener(click, handleClick) }, unmounted(el) { const state getPressState(el) if (state) { clearTimer(state) pressStateMap.delete(el) } el.removeEventListener(touchstart, handleTouchStart) el.removeEventListener(touchmove, handleTouchMove) el.removeEventListener(touchend, handleTouchEnd) el.removeEventListener(touchcancel, handleTouchCancel) el.removeEventListener(mousedown, handleMouseDown) el.removeEventListener(mousemove, handleMouseMove) el.removeEventListener(mouseup, handleMouseUp) el.removeEventListener(mouseleave, handleMouseUp) el.removeEventListener(click, handleClick) }, }这段代码里有一个需要注意的设计监听器函数全部定义在模块顶层通过this获取当前元素。因为addEventListener在调用时会自动把this指向绑定元素所以handleTouchStart里的this就是指令所在的 DOM 元素。这样做的好处是多个元素共用同一批函数不产生闭包泄漏同时每个元素的状态通过 WeakMap 独立保存不会发生“元素 A 的定时器把元素 B 的长按给触发了”这种鬼畜问题。3.3 注册与使用方式指令写好后注册非常灵活。如果你在组件里使用script setup最省事的办法是直接把vLongPress导入组件中使用script setup langts import { vLongPress } from /directives/longPress function openMenu() { // 打开操作菜单 } /script template div v-longPressopenMenu classlist-item 长按我试试 /div /template如果你需要传参数就传一个对象template div v-longPress{ delay: 800, moveThreshold: 8, onStart: () setPressing(true), onTrigger: openMenu, onCancel: () setPressing(false), } {{ pressing ? 正在按压 : 按住我 }} /div /template如果要求全局注册常规做法是在main.ts里import { createApp } from vue import App from ./App.vue import { vLongPress } from ./directives/longPress const app createApp(App) app.directive(longPress, vLongPress) app.mount(#app)模板里就能直接写v-longPress不需要每个组件重复导入。指令支持函数和对象两种写法函数写法等价于只传onTrigger适用于“长按后只做一件事”的简单场景。4. 核心逻辑拆解计时、状态与事件冲突的消除4.1 WeakMap 状态管理多个元素互不干扰长按指令最初的实现我试过把状态直接挂在全局变量里结果在表格里一用就出问题按了第一行还没松手又按第二行两个元素共用了同一个timer第二个元素按下时直接把第一个的计时器给清了长按总在关键时刻失效。后来改成每个元素一个状态对象用 WeakMap 保存。WeakMap 在这里有两个好处键是 DOM 元素对象本身不需要给元素加自定义属性避免污染 DOM当元素被 Vue 移除并且没有其他引用时WeakMap 中的记录可以被垃圾回收不会造成内存泄漏。指令的mounted里创建状态unmounted里清空定时器并删除状态这跟 Vue2 时代的inserted/unbind思路一致但 Vue3 的生命周期钩子更直观命名也更统一。4.2 setTimeout 计时方案与为什么不需要轮询长按计时的核心非常简单按下时启动setTimeout到点后设置triggered true并执行onTrigger如果提前松手或位移超限则clearTimeout取消计时。为什么不用Date.now()加setInterval每帧轮询因为长按本身并不需要高频率更新——你只要知道“够不够 600ms”这一个信息一个定时器就完成了。轮询的意义在于“过程中需要持续反馈”比如长按进度条那是另一个场景我放到最后一部分再说。用一个定时器还有一个好处中断逻辑非常清晰所有取消路径都调用clearTimer即可不会出现多个定时器叠加导致回调次数不可控的情况。4.3 位移阈值判定长按和滚动/拖拽的边界移动端最典型的冲突是用户在滚动列表时手指会先轻微停留在某个列表项上然后才开始滑动。如果没有位移判定这种场景会被误判为长按。所以touchmove里我记录了触点相对起点的位移一旦横向或纵向位移超过moveThreshold就判定为用户意图是滚动而不是长按立即取消计时。一个很关键的细节是touchstart和touchmove监听器要传{ passive: true }。这样做的原因是告诉浏览器我们不会在这两个事件里调用preventDefault浏览器可以放心地处理默认滚动行为。如果你在touchmove里preventDefault页面会变得非常“卡手”滚动不顺畅这会直接影响整体体验。移动端长按和滚动能否共存靠的就是这个 passive 配置和位移阈值而不是粗暴地禁止滚动。4.4 消灭合成 click 的“二段触发”长按结束后最烦人的问题就是用户都已经长按呼出菜单了松手时系统又给一次 click结果把菜单旁边的按钮或者当前列表项的默认点击行为又触发了一遍。在指令内部我加了一个click监听逻辑是如果state.triggered为 true表示刚才已经发生了长按默认情况下调用event.preventDefault()和event.stopPropagation()把紧随的 click 拦下来同时把triggered重置为 false保证这一次点击不会影响下一次交互如果业务希望长按后 click 也正常触发就把allowClickAfterLongPress设为 true。这个设计的核心思路是“消费掉一次 click 事件”。因为长按和短按在物理上不可能同时发生所以每次交互只会对应一次“到达阈值”的状态。用布尔标记位来判断是否消费这次 click既简单又可靠。另外mousedown里的suppressMouseUntil窗口也很重要。移动端浏览器合成鼠标事件的时间点左右略有差异设 800ms 窗口是为了留足余量保证 touch 交互期间所有被合成的 mouse 事件都不会重复触发长按计时。5. 实战中踩过的坑与对应的修复方案5.1 移动端长按图片弹出系统菜单实际联调时第一个遇到的是图片问题。列表项里带缩略图移动端长按缩略图时系统会弹出“存储图像 / 拷贝 / 分享”这样的原生菜单整个长按反馈完全被打断。要解决这个问题可以分两层处理。第一层是 CSS给指令作用的元素加上-webkit-touch-callout: none; user-select: none;-webkit-touch-callout是 iOS Safari 里专门控制长按呼出菜单的非标准属性设置为none后长按图片就不会弹系统菜单。user-select: none能防止文本被选中对 PC 端的鼠标长按也有帮助。第二层是拦截contextmenu事件。移动端长按在部分浏览器里也会触发contextmenuPC 端右键也会触发。可以在指令内部监听contextmenu如果当前有按压计时或已经触发了长按就preventDefault()。不过要注意这样会把 PC 端的右键菜单也屏蔽掉所以如果业务需要保留右键菜单这个拦截要做成可配置项不建议硬编码。5.2 PC 端长按拖动选中文本PC 端鼠标按住不松手默认行为会选中元素内部的文本尤其是长按列表文字时经常会看到一段蓝色选区视觉上特别突兀。处理的办法就是全局给长按元素加user-select: none。在现代浏览器里把user-select设为none就可以禁用文本选中。我以前遇到有人直接用mousedown里调用event.preventDefault()这个方法也能勉强生效但副作用是可能妨碍其他默认行为不如 CSS 来得干净。另外如果元素是图片记得加上draggablefalse否则鼠标按住图片会进入拖拽预览态长按状态同样会被破坏。5.3 列表滚动时把“轻微滑动”误判成长按在滚动容器里使用指令时如果用户按住列表项然后上下滑动位移很快会超过 10px 阈值这时候计时器会取消这是正确的。真正容易出问题的是“按住后缓慢滑动”位移在边界值附近徘徊一会儿超一点一会儿又没超导致长按触发的不确定性增加。我最后做的处理是位移一旦超过阈值就立即取消且不可逆不存在“滑回来又恢复计时”的逻辑。这种一刀切的做法在体验上是合理的因为用户一旦开始滑动意图就已经从“按住”变成了“移动”不应该因为回到原点又重新变成长按。如果你在调试时发现长按偶尔触发、偶尔不触发优先怀疑的就是没有做“一次性位移判定”。5.4 指令卸载后定时器残留导致的内存泄漏这个坑在 v-for 场景下最容易发生。列表项在滚动时被虚拟滚动组件卸载如果unmounted里没有清理定时器而定时器到点后回调还在执行就会出现回调里访问的响应式数据已经被销毁控制台报 warning定时器持续引用旧的 DOM 元素和业务闭包内存无法释放。所以unmounted里不仅要移除事件监听器还要调用clearTimer(state)把未完成的setTimeout清掉。代码里我把clearTimer独立成一个函数所有取消路径都走它就是为了保证这一点。多人协作时别人改指令逻辑也不容易漏掉清理这一步。5.5 鼠标移出元素后松手长按状态无法结束PC 端还有一个非常隐蔽的问题用户按住元素然后不松手直接把鼠标拖到元素外面再松开。这时候mouseup并没有在指令元素上触发如果只监听mouseup定时器会一直挂在那里需要等下一次交互才能被重置。解决方案有两个方向监听mouseleave鼠标移出元素时立即取消长按在mousedown时把mouseup监听器临时挂到window上松手后再移除。第一种方案更简单但会导致“按住后拖出元素就无法触发长按”的情况第二种方案更符合长按的物理过程——用户只要没有松手即使鼠标移出元素长按依然可以继续。我目前代码里用的是折中方案监听mouseleave调用一次handleMouseUp既保证取消及时也不会引入额外的 window 级监听器。如果你的业务需要支持“按住元素后拖到外部继续触发”可以考虑升级为 window 级 mouseup。6. 进阶扩展进度反馈、PointerEvent 方案与后续玩法6.1 按住过程中的进度反馈有些场景不满足于“到点触发”比如长按呼出菜单之前希望有一个圆环进度或者颜色渐变让用户直观看到“还差多少毫秒”。这时候只靠一个setTimeout就不够了需要更细的时间更新。我用requestAnimationFrame写了这套逻辑的大致结构function startProgress(state: PressState, startTime: number, callback: (progress: number) void) { const tick () { const elapsed Date.now() - startTime const progress Math.min(elapsed / state.options.delay, 1) callback(progress) if (progress 1) { state.rafId window.requestAnimationFrame(tick) } } state.rafId window.requestAnimationFrame(tick) }在onStart时记录startTime按 delay 算进度长按触发或取消时记得cancelAnimationFrame。这个方案比setInterval更平滑也不会在页面后台运行时浪费性能。如果你不想引入 rAF用 setInterval 也是可行的只是视觉流畅度会略差。6.2 现代项目可以直接用 PointerEvent 精简实现如果你的项目最低浏览器版本比较高不包含历史遗留的移动端 WebView可以考虑用 PointerEvent 重写一个精简版代码量会少非常多import type { Directive } from vue const vPointerLongPress: DirectiveHTMLElement, { delay?: number; onTrigger?: () void } { mounted(el, binding) { let timer: number | null null let startX 0 let startY 0 el.addEventListener(pointerdown, (e) { startX e.clientX startY e.clientY timer window.setTimeout(() { binding.value?.onTrigger?.() }, binding.value?.delay ?? 600) }) el.addEventListener(pointermove, (e) { if (timer null) return const distance Math.hypot(e.clientX - startX, e.clientY - startY) if (distance 10) { clearTimeout(timer) timer null } }) el.addEventListener(pointerup, () { if (timer) clearTimeout(timer) timer null }) }, }前提是给指令元素加上touch-action: none否则移动端浏览器会在判定滚动时发送pointercancel长按会被中断。touch-action: none的直接效果是让元素不参与默认的触摸滚动和缩放这在需要长按的局部区域是完全合理的但如果你同时希望元素内部还能上下滚动就要慎重权衡了。6.3 长按加拖拽组合以及更多后续玩法长按指令稳定之后可以继续扩展成更复杂的手势。最常见的是“长按后拖拽排序”先按住元素超过阈值进入拖拽模式然后手指移动时不再是取消长按而是把位移量传给业务层用来更新拖拽位置。这个扩展点在于touchmove处理逻辑位移小于阈值时取消长按位移大于阈值且已经触发长按时应该把clientX - startX和clientY - startY作为拖拽偏移量暴露出去而不是一律取消。我把moveThreshold设计成独立参数就是为了这种场景后做到的“先判定意图再决定去向”。至于连续触发、防抖节流、表单按钮误触之类的场景其实都可以在这个基础上用参数组合拼出来。指令只负责把“按下的时间 位移约束 双端差异”收敛掉业务层想怎么用都很自由。最后分享一个调试小技巧真机上调试长按时序时与其靠感觉猜不如在onStart、onTrigger、onCancel三个回调里各打一条日志然后在浏览器设备模拟器里按住观察日志顺序这样能很快定位到底是计时被取消了还是 click 冲突没消掉。我每次接到长按相关的 bug 反馈都是先看这三条日志基本十次能中九次。