H5振动反馈实战：用navigator.vibrate打造buzz模块

做移动端H5的时候，我攒了一个叫“buzz”的小模块。项目代号就一个字，buzz，干的事也跟这个单词的本意一样：让手机在合适的时机“嗡”一下。说白了就是调用浏览器自带的振动接口，给页面加上真实的触觉反馈。这个需求一开始看着不起眼，不少人觉得不就一个navigator.vibrate()的事吗，可真要做得稳、做得不突兀、兼容性问题处理干净，里面坑比想象中多得多。这篇文章把我踩过的坎、想清楚的逻辑和最终落地的方案完整写出来，给做H5互动、移动端WebApp和混合应用的朋友一个可以直接抄作业的参考。

1. 这个叫“buzz”的项目到底做了什么

1.1 一个被忽略的反馈通道

人类接收信息靠的不只是眼睛和耳朵，触觉是更原始、更直接的一条通道。你在手机上打字、玩游戏、按实体键，那种“咯噔”一下的手感，本质上就是设备在给你发送触觉信号。但在Web页面里，这个通道常年是断的。

我之前接的那个H5项目是个互动营销页面，有刮奖、抽奖转盘、答题闯关这些玩法。每次抽奖结果出来，页面上当然有动画、有弹窗，视觉反馈很丰富，但用户手指在屏幕上点来点去，却感觉“轻飘飘”的。尤其是在比较嘈杂的环境里，用户可能根本没注意到结果已经弹出来了。

当时产品提了一个很朴素的需求：能不能让手机振一下？让用户手上的感觉告诉他“结果出来了”。说实话这个需求在移动端原生App里很容易实现，但我们是H5页面，跑在浏览器里，当时团队里一半人不知道浏览器还能控制手机振动。

其实浏览器还真的能，这就是Web Vibration API，常用的就是navigator.vibrate()这个方法。它在Android生态里的Chrome、Firefox以及大部分国产浏览器内核中都有良好支持，而在iOS Safari上至今仍在“计划中”。我做的buzz模块，就是围绕这个API做的一整套封装、降级和体验优化方案。

1.2 这个模块的目标和边界

项目代号叫buzz，目标非常聚焦：给H5页面提供一套简单、统一、可控的振动反馈能力，同时在不支持振动的环境下自动降级，不破坏原有体验。

我给自己定的边界很明确：只做“反馈”，不做“输入”。也就是说buzz只管在合适的时机发出振动信号，不管用户手指怎么滑、怎么按。另一个边界是，buzz不负责业务逻辑的编排，只提供一个一个的“手势”，拿“抽奖结果”这种业务事件来说，业务方决定什么时候触发，buzz决定怎么振，两边职责分开。

做了一段时间后，我越发觉得这个模块值得单独拎出来讲。因为“让页面会振动”这件事，看起来是加几行代码，实际上牵扯到兼容性判断、振动模式设计、页面生命周期管理、用户手势限制、甚至和音频反馈的配合。这些问题如果不在设计初期想清楚，后面越用越别扭。

2. 技术底座：Web Vibration API关键知识点

2.1 先认识navigator.vibrate()这个老朋友

Web Vibration API，规范上叫Vibration API，它的核心入口就一个方法：navigator.vibrate()。这个API的兼容性列表在caniuse里看很直观：Android Chrome从37开始支持，Android Firefox从32开始支持，包括三星、小米、华为等自带浏览器基本都通过了WebView内核的Chromium，所以在Android这边可以说是“基本全线可用”。iOS Safari直到我写这套方案的版本都还没真正开放振动权限，页面里调用它只会静默失败。

navigator.vibrate()接受一个参数，可以是数字，也可以是数字数组。传数字时表示持续振动多少毫秒，比如navigator.vibrate(200)就是让手机持续振动200毫秒。传数组时，数组的每个元素交替表示“振动”和“停止”的毫秒数，例如[200, 100, 200]就是振动200ms、停100ms、再振动200ms。数组第一个数一定是振动，即使你传了0开头，那也只是“先停0ms”再进入下一个振动段。

这里有个细节值得注意：持续振动的时长上限。虽然在规范文档里没有硬性规定上限值，但浏览器实现中普遍对超长的振动做了截断。以Android Chrome为例，当连续振动时间超过某个阈值（不同版本不完全一样，大概在10秒到1分钟之间），浏览器会直接截断。原因是设计振动API的初衷是给人“短暂反馈”，不是拿手机当按摩棒。

2.2 数组模式才是振动体验的灵魂

很多人第一次接触这个API，以为只能做“嗡嗡嗡”的直振，其实不是。数组参数可以做到非常细腻的振动节奏，这才是buzz模块的核心价值所在。

举几个实际的例子：

// 短促的轻击，适合按钮按下 navigator.vibrate(15); // 清脆的两连击，适合结果弹出 navigator.vibrate([30, 50, 30]); // 三段式提醒，模式比较强烈，适合警告 navigator.vibrate([80, 40, 80, 40, 80]); // 长按触发的持续振动 navigator.vibrate([50, 20, 50, 20, 100]);

数组模式的本质是用“振动 - 停顿 - 振动”的时间序列来组合出不同的手感。就像摩斯电码一样，短振和长振组合起来，就能传递出不同的语义。这比简单的“持续振动200ms”高级得多，因为200ms的持续振动无论用在哪个场景都是同一个感觉，而数组模式可以设计出“轻触”“确认”“警告”这种有差异的反馈语言。

我实际测试下来，短振动的时长设计非常讲究。15ms已经能产生清晰的触感，但不会让人觉得很吵。30ms更像一次明确的“嗒”感。超过100ms的连续振动就有点“厚重”了，一般用于需要强烈提醒的场景，不能滥用。设计buzz的模式库时，我反复调整了不下十版，最后定下来的模式在我自己真机测试里达到了“既明显又不恼人”的效果。

2.3 浏览器运行条件：HTTPS、用户手势和页面可见性

任何Web API都有运行条件，Vibration API也不例外。这个API只能在安全上下文（HTTPS或localhost）中调用，如果你在HTTP环境下打开页面，navigator.vibrate根本不存在或者会被策略拦截。混合应用里如果你的WebView原生层配置了允许不安全的来源，那又是另一回事，但常规的线上H5一定要走HTTPS。

更隐蔽的一个条件是：用户手势。大多数移动端浏览器要求振动API必须在用户手势事件（比如touchstart、click、pointerdown）的调用栈里执行，不能莫名其妙地在页面刚加载完时自己振一下。Chrome Android在早期版本里还允许任意时机调用，后来也收紧了这个策略，和自动播放限制差不多，都是为了防止页面骚扰用户。实际下来，在一个setTimeout里调用navigator.vibrate(200)，如果定时器是在点击事件的回调里启动的，一般没问题；但如果是在页面初始化时凭空调用的，很可能被当作“无用户参与的振动”而被忽略。

页面可见性也要考虑。如果用户已经切到后台或锁屏了，振动会被系统静默，或者继续响应但是在锁屏界面振动，这个体验非常突兀。buzz模块在设计初期就在visibilitychange事件上挂了清理逻辑，页面一藏起来就立刻终止所有振动。

3. 设计buzz模块时的方案选型

3.1 不是简单包一层，而是设计一套反馈语言

很多人的第一反应是写个公共函数：

function buzz(pattern) { if (navigator.vibrate) navigator.vibrate(pattern); }

这种写法可以用在小项目里，但它的缺陷也很明显：没有模式管理、没有防抖、没有降级、没有生命周期处理。如果只是某个按钮加一次振动，这样够了。但如果我们想在整个项目里形成一套一致的手感，就必须把“怎么振”这件事抽象出来，定成一套规范。

我管这叫“反馈语言”。就像设计系统会规范颜色、字体、间距一样，振动反馈也应该有它自己的语义化标签。比如：light指那种极短促的轻触，confirm指操作成功后的确认感，warning指强烈提醒。业务方不应该关心具体振动模式是[30, 50, 30]还是[15]，他们只需要说“这里我想给个确认反馈”，buzz自动映射到具体的振动序列。这样视觉、交互、前端三方沟通时，就有一门共同语言。

3.2 模块结构：一个VibrationManager

buzz模块最终设计成了一个单例管理器，核心结构大概长这样：

const DEFAULT_PATTERNS = { light: 15, tap: [15, 30, 15], confirm: [30, 50, 30], success: [40, 30, 15, 30, 40], warning: [80, 40, 80, 40, 80], }; class VibrationManager { constructor() { this.enabled = this.isSupported(); this.locked = false; } isSupported() { return typeof navigator !== 'undefined' && 'vibrate' in navigator; } fire(type) { if (!this.enabled || this.locked) return; const pattern = DEFAULT_PATTERNS[type]; if (!pattern) return; try { navigator.vibrate(pattern); } catch (e) { // 捕获异常，振动失败绝不影响业务 } } stop() { if (this.enabled) { navigator.vibrate(0); } } lock() { this.locked = true; } unlock() { this.locked = false; } } const vibrationManager = new VibrationManager();

这个类还有一个lock机制，用于处理连续触发的场景。比如用户连点三次抽奖按钮，如果每次点击都触发一次success振动，三次振动指令会叠加在振动队列里，实际效果就是“振了一长串”，非常糟糕。加上锁后，在振动进行期间忽略新的振动请求，等振完再解锁。后面踩坑章节我还会详细讲这个问题。

3.3 降级策略：在没有振动能力的平台制造“替代手感”

iOS Safari不支持振动，这是Web平台上永远绕不开的现实。难道iOS用户就不配拥有反馈吗？显然不是。我的处理方式是引入“视觉补偿反馈”。

降级的核心思路是：把“振动”这个触觉信号，转换成用户能感知到的视觉信号。比如按钮被按下时，本来应该振一下，在iOS上我就给按钮添加一个瞬时的缩放动画，有点像原生iOS按钮的按压效果。动画时长极短，大约100到150ms，用来模拟那种“咯噔”的阻尼感。

.btn-pressed { animation: buzz-feedback 120ms ease-out; } @keyframes buzz-feedback { 0% { transform: scale(1); } 40% { transform: scale(0.95); } 100% { transform: scale(1); } }

这种降级不是单纯地“没有就没有”，而是用另一种通道尽量填补体验空缺。实际体验中，这种按压缩放配合轻量的透明度变化，能比较有效地补偿振动缺失的手感。当然视觉补偿不能替代真正的触觉，但它至少让iOS用户不会觉得“点起来轻飘飘”。

4. 核心实现细节与实操要点

4.1 反馈模式设计：定义一套“手感词汇表”

模式设计是整个buzz模块我认为最值得反复琢磨的部分。振动模式既不能太轻导致感知不到，也不能太重导致像骚扰电话。我把常用模式分成几个层级，每个层级服务于不同的交互场景。

• light级别，对应最普通的按钮触摸反馈，一般是15ms左右的单次短振。这个时长在Android上刚好能产生明确的触点感受，不会让整机震动，听起来像“嗒”一下。
• tap级别，对应需要强调的离散操作，比如开关切换、标签选择，模式是[15, 30, 15]，两下短促的振动足够让人知道切换生效了。
• confirm级别，对应操作成功的确认，模式是[30, 50, 30]，比tap更加“稳”一点，有明确的起止感。
• success级别，对应流程完成的庆祝感，比如抽奖结果弹出、任务达成，模式是[40, 30, 15, 30, 40]，这段模式在真机上听起来像“嗒—嗒嗒—嗒”，比较有节奏。
• warning级别，对应错误或强提醒，模式是[80, 40, 80, 40, 80]，振感强、时间长，一般用于需要用户警觉的场景。

每个模式我都用真机测过。要注意的是，同一段模式在不同手机上的实际体验差异极大：转子马达和线性马达的启动延迟不一样，低端机反应迟钝、高端机干脆利落。所以不能把我们代码里的振动参数当成绝对标准，只能在真机上反复微调，找到绝大多数设备都能感知的区间。

4.2 把werkzeug放在一边：如何正确接入业务事件

buzz模块本身不感知业务，它只提供fire(type)这样的出口。但如何接入业务事件是有讲究的。我在项目里做了事件桥接层，让业务方通过一个语义化的方法调用，而不是直接操作振动对象。

比如抽奖结果回来时，业务代码是这样的：

function handleLotteryResult(success) { if (success) { vibrationManager.fire('success'); } else { vibrationManager.fire('warning'); } showResultModal(success); }

调用方只关心是成功还是失败，具体振多长时间、振动几次，由buzz在内部决定。好处是当我们需要调整振动模式时，只需要改模式表，不需要满项目搜索调用点。随着页面越来越多，不同页面可能对同一种反馈有不同偏好，我还在模块里支持了全局模式和临时覆盖模式，但默认情况下保证所有页面手感一致。

4.3 页面生命周期与性能优化细节

移动端页面的生命周期远比PC复杂，振动模块必须对它敬畏。我把visibilitychange事件和一个页面卸载清理逻辑直接写进了模块内部。当页面不可见时，立即调用navigator.vibrate(0)把振动队列清空，防止用户把页面切后台后手机还在怀里嗡嗡响。

document.addEventListener('visibilitychange', () => { if (document.hidden) { vibrationManager.stop(); } });

这段逻辑看起来简单，但它解决了很多没做过振动开发的开发者不会想到的问题：用户可能正在点按钮，此时突然来电提醒，页面切到后台，如果没有清理逻辑，振动会和来电冲突，结果非常尴尬。

性能方面，振动API本身不涉及图形渲染，但它经常在动画代码中触发。如果动画帧率本来就低，再叠加振动调度，可能会让低端机的页面更卡。我的建议是振动调用一律放在主线程的事件回调里，不要频繁地在requestAnimationFrame循环里反复触发振动命令。还有一点，不要在滚动容器里监听滚动事件来触发振动，滚动频率太高，这样既有性能问题，也会因为连续振动让用户觉得页面“疯了”。如果需要滚动到某个位置时给一个反馈，应该做节流。

4.4 振动与音频反馈的联动

单纯的手部振动，再加上同步的音频反馈，整体感觉会立刻立体起来。最简单的做法是，同一个事件既触发振动，又播放一个极短的音效。比如点击按钮时，同时“嗒”一声和“嗡”一下，反馈就非常完满了。

但AudioContext在移动端的自动播放限制同样存在。Chrome要求必须先有用户手势才能解锁音频上下文。所以我在buzz里设计了一个统一的唤醒入口：

const audioCtx = new AudioContext(); function playClickSound() { // 必须确保 audioCtx 已经处于 running 状态 if (audioCtx.state === 'suspended') { audioCtx.resume(); } // 创建一个极短的 osc 音 const osc = audioCtx.createOscillator(); const gain = audioCtx.createGain(); osc.connect(gain); gain.connect(audioCtx.destination); osc.frequency.value = 800; gain.gain.setValueAtTime(0.2, audioCtx.currentTime); gain.gain.exponentialRampToValueAtTime(0.001, audioCtx.currentTime + 0.05); osc.start(); osc.stop(audioCtx.currentTime + 0.06); }

注意这个audioCtx.resume()必须在用户点击事件里调用，否则会被浏览器拒绝。同理振动API的执行也必须发生在用户手势链中。实际经验是把音频和振动放在同一个事件回调里，让两条反馈同时触发，减少因为异步拆开导致的违反手势策略风险。

5. 实测过程与踩坑记录

5.1 真机测试：哪些设备振，哪些设备不吭声

做移动端开发，模拟器永远代替不了真机。buzz模块的真机测试，我专门拉了一张兼容性表，把同事手上的备用机都借来测了一遍，结果比caniuse的数据有意思得多。

这里有个结论：同样一段[30, 50, 30]，在小米浏览器上感知很弱，在最新Chrome上就很清楚。原因是线性马达和转子马达的差异，以及各家系统对振动API的实现差异。所以做模式设计时不能只在一台高端旗舰机上调，一定要拿几台中低端机做对照。

5.2 踩坑一：iOS Safari完全不支持，怎么让测试通过

iOS不支持，在大部分项目里并不算Bug，因为页面本身在iOS上可以正常运行，只是没有振动反馈。问题在于，如果产品经理和测试抱着“必须有反馈”的预期去验收，就会被打回。

我的处理办法是提前把降级方案做在前面，并在项目文档里写明确：iOS上使用按压缩放动画替代振动。这样测试验收时，iOS上的确也能看到反馈，不过是视觉层面的，而不是触觉层面的。这个预期管理非常重要，不然等到交付前才被发现，又要手忙脚乱地补方案。

5.3 踩坑二：桌面浏览器调试时完全不振动

开发时如果在桌面Chrome的开发者工具里模拟移动端设备，navigator.vibrate在大部分情况下是存在的，但调用后PC根本没有马达，自然不会有任何反馈。所以很多人在电脑上调了一下午，以为代码有问题，其实只是桌面硬件不支持。

解决方式：用Android真机开启USB调试，通过chrome://inspect远程调试页面的实际运行效果，或者在本地局域网用手机直接访问开发服务器。真机上的反馈才是唯一的验证标准，开发者工具只能用来验证API是否存在、参数是否正确。

5.4 踩坑三：连续触发振动，变成一股又长又乱的振动

这个坑我真正踩实过，也是buzz模块引入lock锁机制的直接原因。假设用户连点三下按钮，三次click事件各调用了一次fire('success')。如果不加控制，浏览器会把三次振动模式塞进同一个振动队列，振出来就是“嗡——嗡——嗡——”的长条，完全失去了模式的意义。

解决方案除了lock锁，还有一个更精细的做法：记录上一次振动的结束时间，如果新请求到来时上一种模式还没振完，先调用一次navigator.vibrate(0)清空队列，再调用新模式。两种方案各有选择，lock更适合“一次操作一个反馈”的交互，而清队列适合“允许连续反馈但每次都要完整呈现”的场景。

5.5 踩坑四：页面里多个buzz实例互相打架

早期代码里我图省事，直接在组件里创建了多个VibrationManager，结果A组件的振动还没结束，B组件又振了一下，整个页面的振动节奏全乱了。后来我把VibrationManager改成了单例模式，整个页面只有一个入口，才解决了这个互相覆盖的问题。

这个教训让我想明白一件事：像振动这种全局性的反馈通道，就不应该设计成“每个组件私有”的东西。反馈是一套系统，不是某种局部状态。这一点跟全局Toast提示是一样的道理，你不希望页面上同时冒出十个Toast。

6. 常见问题与排查技巧实录

6.1 常见问题速查表

我把实际运行中收集到的典型问题整理一下，做成速查表，方便后续维护的同学快速定位。

6.2 排查思路：从“不振动”到“振错了”

遇到振动相关问题时，我有一套固定的排查顺序。先确认协议环境，看页面是否在HTTPS下；再确认调用时机，是不是在用户手势事件里；接着确认设备能力，navigator.vibrate是否存在；最后确认队列状态，是不是被之前的振动占用。这套顺序能解决70%以上的问题。

还有个小技巧：调试时在控制台手动执行navigator.vibrate([100, 50, 100])，如果真机通过USB远程调试连接着，直接就能在手机上感受到效果。这比反复刷新页面改代码高效得多。控制台执行时也是从用户手势上下文中调用的，通常能通过浏览器策略限制。

6.3 独家避坑：千万别让buzz成为“报警器”

在项目推广阶段，我观察到一种滥用倾向：业务方觉得振动很酷，于是按钮、弹窗、轮播都加上了振动反馈。到最后用户打开页面，手机像马达一样震个不停，结果变成了负体验。后来我发起了一个“振动礼仪”约定：只有真正需要用户感知节点时才启用振动，普通滑动、次要按钮不加振动；同一个交互流程内最多触发一次振动；默认模式下振感不超过200ms。

这个约定的效果立竿见影。页面整体的“手感”反而变好了，用户能感知到的振动都是关键节点的信号，而不是噪音。现在我把这条经验写进模块的Readme里，作为使用规范的一部分。

7. 这个模块后续还可以怎么扩展

7.1 结合Gamepad API的探索

Web平台上有另一个跟“反馈”相关的API，Gamepad API，它允许浏览器读取游戏手柄状态，并且一些手柄带有振动马达，可以通过navigator.getGamepads()拿到的hapticActuators来触发振动。虽然目前这个能力和移动端关系不大，但如果页面未来要支持连接到手机上的蓝牙手柄，这套震动反馈机制可以复用buzz的模式设计思路，只是调用对象不同。

7.2 长按振动与“模拟强度”

原生API其实没有提供振动强度的控制，只能通过振动时长和间隔来模拟。我后来做了一个长按交互的实验：用户长按按钮时，用setInterval循环执行短促振动，并且随着长按时长增加，逐步把振动时间从15ms加长到60ms。这样在手感上会产生一种“振动变强”的幻觉。虽然它不如原生触觉API细腻，但在Web端已经是一种很实用的模拟方案。

实现要点是，interval的回调里同样要检查页面可见性和振动状态，否则长按期间用户切到后台，定时器还在触发振动，就会造成持续的骚扰。

7.3 把手感当成产品设计的一部分

buzz模块做到后面，我发现它已经超越了“调用一个API”的技术层面，变成了一种设计语言。靠谱的反馈设计原则无非就三条：短促、少次、有语义。短促指振动时长尽量短，少次指单次操作只振一下，有语义指每种反馈都要有明确的意义，不能所有场景都用同一个模式。

这几条我写在了模块的规范文档里，新同学接手项目时，先看文档就知道什么场景该用light、什么场景应该用success，不需要靠猜。

如果再重新做一遍这个模块，我会把“反馈模式表”单独抽成一个配置文件，方便运营配置不同的手感风格。目前的版本还是硬编码在代码里，改动一次要发一次版。接口设计上也可以再抽象一层，让buzz同时支持振动和视觉补偿两种输出，由内部根据环境自动切换，调用方完全无感。这个方向在Web标准演进之后，说不定还能对接更底层的Haptic API。对我来说，buzz这个项目的价值不只是让页面会振，而是让我明白了一个道理：反馈的终极目标不是“有多明显”，而是“刚刚好”。