Gamepad API 手柄控制层采用事件监听+主动轮询+状态映射，首次调用 navigator.getGamepads() 需用户手势触发；连接靠 gamepadconnected/gamepaddisconnected 事件管理；输入在 requestAnimationFrame 中轮询，加死区与状态比对防误触；映射适配不同手柄布局，支持 standard 标准、厂商识别与手动校准；增强震动反馈、空值防护、帧率控制及键盘降级提示。

直接用 Gamepad API 构建手柄交互控制层，核心是“事件监听 + 主动轮询 + 状态映射”，不依赖任何 HTML 标签，也不靠用户点击后才启动——但首次调用 navigator.getGamepads() 必须发生在用户手势（如 click、keydown）触发的回调中，否则返回空数组。

连接管理：靠事件，不是靠轮询

手柄插拔不能靠定时检查，必须用原生事件捕获：

• gamepadconnected 触发时，保存 event.gamepad.index 对应的手柄实例，记录其 id 和 mapping（如 "standard" 表示符合通用布局）
• gamepaddisconnected 触发时，从本地缓存中移除对应索引的手柄，避免后续轮询访问已断开设备引发异常
• 多个手柄共存时，按 index 区分玩家，比如 index === 0 分配给 Player 1，index === 1 给 Player 2

输入读取：requestAnimationFrame 中持续轮询

浏览器不会主动推送按键变化，必须自己每帧去问：

前端设计优化skill

前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。

下载

• 在 requestAnimationFrame 循环里调用 navigator.getGamepads()，它返回一个固定长度数组（最大支持 4 个），未连接位置为 null
• 对每个非空 gamepad，遍历 buttons 数组判断 pressed 或 value（带压力感应的按钮）
• 读取 axes 时务必加死区（例如 Math.abs(axis) > 0.15），否则轻微漂移会误触发移动
• 避免重复触发：记录上一帧的按钮状态，仅在 pressed === true && lastPressed === false 时视为“按下”

映射适配：应对不同手柄的物理差异

同一功能在 Xbox、PS5、Switch Pro 手柄上的物理位置不同，不能硬编码索引：

立即学习“前端免费学习笔记（深入）”；

• 优先检查 gamepad.mapping === "standard"，此时按钮顺序遵循 W3C 标准（如 buttons[0] 是 A/X，buttons[1] 是 B/Circle）
• 若 mapping 为空，根据 gamepad.id 字符串粗略识别厂商（如含 "xbox"、"playstation"），再查表匹配键位
• 提供手动校准 UI：让用户依次按下 A/B/X/Y/左摇杆/右扳机等，记录实际触发的索引，生成个性化映射表

体验增强：震动与防错机制

基础操作之外，细节决定沉浸感：

• 震动反馈需先检查 gamepad.hapticActuators?.length，再调用 playEffect("dual-rumble", { strongMagnitude: 0.8, weakMagnitude: 0.3 })
• 所有手柄数据读取前加空值防护：if (!gamepad || !gamepad.connected) return
• 轮询循环中缓存 timestamp，跳过间隔过短的帧（防止高刷屏下高频误判）
• 在无手柄时降级为键盘控制，并在 UI 显示“手柄已断开，按空格重连”等提示