如何让HTML5+JS游戏通过Gamepad API识别USB手柄按键功能？

核心思路 #

Gamepad API返回的按键索引由硬件厂商定义，不同手柄存在差异。解决关键是基于手柄硬件ID做针对性映射，或引导用户手动配置来适配不同手柄的按键布局。

方法一：预定义常见手柄映射表 #

主流手柄（Xbox、PS、Switch Pro等）的按键布局有统一规范，可提前收集它们的gamepad.id特征与对应按键映射：

代码示例 #

// 预定义手柄映射表，key为gamepad.id的特征字符串，value为功能-按键索引映射
const controllerMappings = {
  // Xbox系列手柄（id通常包含"Xbox"）
  "Xbox": {
    up: 12,
    down: 13,
    left: 14,
    right: 15,
    confirm: 0,
    cancel: 1
  },
  // PS系列手柄（id通常包含"PlayStation"或"PS"）
  "PlayStation": {
    up: 12,
    down: 13,
    left: 14,
    right: 15,
    confirm: 0, // 对应PS的Cross键
    cancel: 1  // 对应PS的Circle键
  },
  // 某小众手柄（id包含"CustomPad"）
  "CustomPad": {
    up: 5,
    down: 6,
    left: 7,
    right: 8,
    confirm: 1
  }
};

// 根据手柄ID匹配对应映射
function getControllerMapping(gamepad) {
  for (const [key, mapping] of Object.entries(controllerMappings)) {
    if (gamepad.id.includes(key)) {
      return mapping;
    }
  }
  // 未知手柄返回默认映射
  return {
    up: 12,
    down: 13,
    left: 14,
    right: 15
  };
}

// 游戏主循环处理输入
function gameLoop() {
  const gamepads = navigator.getGamepads();
  for (const gamepad of gamepads) {
    if (!gamepad) continue;
    const mapping = getControllerMapping(gamepad);
    
    // 检测上按键按下
    if (gamepad.buttons[mapping.up].pressed) {
      player.moveUp();
    }
    // 其他功能同理
    if (gamepad.buttons[mapping.down].pressed) {
      player.moveDown();
    }
  }
  requestAnimationFrame(gameLoop);
}

// 监听手柄连接事件
window.addEventListener("gamepadconnected", (e) => {
  console.log(`已连接手柄：${e.gamepad.id}`);
});

方法二：用户手动配置按键 #

针对小众未知手柄，预定义映射无法覆盖，可做按键配置界面：

实现步骤 #

1. 弹出配置界面，提示用户按下对应功能的按键（如“请按向上移动的按键”）。
2. 监听gamepadbuttonup事件，记录按下的按键索引并绑定到对应游戏功能。
3. 将配置保存到localStorage，下次启动自动加载。

代码示例 #

// 加载用户自定义映射
let userMapping = JSON.parse(localStorage.getItem("gamepadMapping")) || {};

// 启动按键配置流程
function startKeyConfig(feature) {
  console.log(`请按下对应【${feature}】的按键`);
  const configHandler = (e) => {
    const pressedIndex = e.button;
    // 绑定功能与按键
    userMapping[feature] = pressedIndex;
    // 保存到本地
    localStorage.setItem("gamepadMapping", JSON.stringify(userMapping));
    console.log(`已绑定【${feature}】到按键索引${pressedIndex}`);
    window.removeEventListener("gamepadbuttonup", configHandler);
  };
  window.addEventListener("gamepadbuttonup", configHandler);
}

// 使用用户配置处理输入
function handleGamepadInput(gamepad) {
  if (userMapping.up && gamepad.buttons[userMapping.up].pressed) {
    player.moveUp();
  }
  if (userMapping.down && gamepad.buttons[userMapping.down].pressed) {
    player.moveDown();
  }
}

额外注意事项 #

• 摇杆输入可通过gamepad.axes数组处理（值范围-1到1），补充十字键的控制场景。
• 按键的value属性（0到1）可处理压力感应按键（如PS手柄的按压程度）。
• 监听gamepaddisconnected事件，及时清理断开手柄的资源。

内容的提问来源于stack exchange，提问作者idk