web-haptics

安装 web-haptics（npm i web-haptics），并按照以下规则为应用添加触觉反馈：

软件包：web-haptics

仓库：https://github.com/lochie/web-haptics | 许可证：MIT | 零依赖

使用 Web Vibration API。在不受支持的平台（桌面设备）上会静默地不执行任何操作。无需错误处理或功能检测。

触发类型

trigger() 接受以下字符串之一（空值默认为合理的“中等”冲击）：

通知（任务结果）：

• "success" -- 表单已保存、付款已确认、上传已完成
• "warning" -- 即将执行破坏性操作、接近限额、不可逆步骤
• "error" -- 验证失败、网络错误、权限被拒绝

冲击（物理碰撞）：

• "light" -- 小型切换、轻触、轻微交互
• "medium" -- 按钮按下、卡片吸附到位、放置到位
• "heavy" -- 重大状态变化、重物落下、用力按压

选择（离散步进）：

• "selection" -- 选择器滚动、步进器递增、滑块卡点、切换分段

框架导入

React：

import { useWebHaptics } from "web-haptics/react";

const haptic = useWebHaptics();

<button onClick={() => haptic.trigger()}>Tap me</button>;

Vue：

<script setup>
import { useWebHaptics } from "web-haptics/vue";
const haptic = useWebHaptics();
</script>

<template>
  <button @click="haptic.trigger()">Tap me</button>
</template>

Svelte：

<script>
  import { createWebHaptics } from "web-haptics/svelte";
  import { onDestroy } from "svelte";
  const haptic = createWebHaptics();
  onDestroy(() => haptic.destroy());
</script>

<button on:click={() => haptic.trigger()}>Tap me</button>

原生 JS：

import { WebHaptics } from "web-haptics";

const haptics = new WebHaptics();
haptics.trigger(); // medium impact
haptics.trigger("success");

Next.js：在任何使用 useWebHaptics() 的组件中添加 "use client"。 Nuxt/SvelteKit：可直接使用，库会处理 SSR。

触发预设与 defaultPatterns

所有命名字符串预设在 defaultPatterns 中都有对应对象。如果需要将预设作为值传入，而不是使用字符串字面量，请使用该对象：

import { WebHaptics, defaultPatterns } from 'web-haptics'

const haptics = new WebHaptics()
haptics.trigger(defaultPatterns.light)

上文未列出的额外预设："soft"、"rigid"、"nudge"、"buzz"。所有可用值请参阅 defaultPatterns。

Apple HIG 设计规则——请遵守

1. 触觉反馈只能作为补充，不能取代其他反馈。务必搭配视觉反馈。没有触觉反馈时，UI 也必须能正常使用。
2. 建立因果关系。触觉反馈必须让人感觉是用户操作直接造成的物理结果。
3. 根据重要程度匹配强度。轻微交互 = light/selection。常规操作 = medium/success。重大操作 = heavy/error/warning。
4. 不要过度使用。如果每次点击都会振动，就没有什么能让人感到特别。仅在有意义的时刻使用。
5. 精确同步。在视觉变化发生的确切时刻触发触觉反馈。
6. 遵循约定。success=积极，error=负面，warning=提醒，selection=仅用于离散刻度。
7. 对于异步操作，在收到结果时触发，并与视觉状态变化同步：

   try {
     await submit();
     haptic.trigger("success");
   } catch {
     haptic.trigger("error");
   }
   

交互与类型速查

主按钮点击 = "medium" | 次要按钮 = "light" 表单成功 = "success" | 验证错误 = "error" | 网络错误 = "error" 切换开关 = "light" | 确认前删除 = "warning" 选择器/滚轮 = "selection" | 滑块卡点 = "selection" | 切换标签页 = "selection" 拖放吸附 = "medium" | 长按 = "heavy" | 模态框出现 = "medium" 下拉刷新阈值 = "light" | 滑动关闭阈值 = "light" 付款已确认 = "success"

反模式——请避免

• 每次点击都触发触觉反馈（会让人疲劳）
• 对非错误使用 "error"（违背约定）
• 没有视觉反馈的触觉反馈（某些设备无法振动）
• 页面加载或被动滚动时触发触觉反馈（有侵入性）
• 对轻微交互使用 "heavy"（令人不适）
• 长时间连续振动（Web 触觉反馈应为短暂脉冲）

开始实现前，请与用户确认：

• 要针对哪些交互元素
• 在共享组件层级还是各个调用点添加