本文深入探讨了在使用html5 gamepad api时，因不当使用解构赋值操作`navigator.getgamepads()`返回值而导致的`typeerror`。文章详细解释了`getgamepads()`的返回类型及其与解构赋值的兼容性问题，并提供了两种正确的获取手柄对象的方法：一种是使用正确的解构赋值语法，另一种是传统的直接索引方式。此外，还强调了处理未连接手柄的健壮性实践和动态手柄检测的重要性。
理解 HTML5 Gamepad API 与 navigator.getGamepads()
HTML5 Gamepad API 提供了一种在网页应用中访问游戏手柄和控制器的方式，为开发者带来了更丰富的交互体验。其核心方法之一是 navigator.getGamepads()，它用于获取当前连接的所有游戏手柄的状态。
然而，在使用此方法时，开发者常会遇到一个常见的 TypeError，尤其是在结合 JavaScript 的解构赋值语法时。要理解这个问题，首先需要明确 navigator.getGamepads() 的返回值类型。
navigator.getGamepads() 返回的是一个 Gamepad 对象的数组或类数组（sequence<Gamepad?>），其中每个元素代表一个连接的手柄。如果某个索引位置没有手柄连接，则对应的值为 null。
解构赋值与 TypeError 的根源
问题代码示例：
立即学习“前端免费学习笔记（深入）”；
window.addEventListener("gamepadconnected", (e) => {
console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
e.gamepad.index, e.gamepad.id,
e.gamepad.buttons.length, e.gamepad.axes.length);
});
// 导致 TypeError 的代码行
const [gp] = navigator.getGamepads()[0];
console.log(gp.axes);当执行 const [gp] = navigator.getGamepads()[0] 时，会抛出 Uncaught TypeError: object null is not iterable (cannot read property Symbol(Symbol.iterator)) 错误。
这个错误的原因在于对 JavaScript 解构赋值的误解以及 navigator.getGamepads() 返回值的处理方式。
- navigator.getGamepads()[0] 的含义： 这段代码尝试直接访问 getGamepads() 返回的类数组的第一个元素。这个元素本身是一个 Gamepad 对象（如果手柄已连接）或 null（如果第一个槽位没有手柄）。
- 解构赋值 const [gp] = ... 的要求： 数组解构赋值 [variable] = iterable 语法要求等号右侧的值必须是一个可迭代对象（如数组、字符串、Map、Set等）。
- 问题所在： navigator.getGamepads()[0] 返回的是一个 Gamepad 对象或 null。Gamepad 对象本身不是一个可迭代对象，null 更不是。因此，尝试将一个非可迭代对象进行解构赋值，就会导致 TypeError。
正确获取 Gamepad 对象的方法
为了避免上述 TypeError，我们可以采用以下两种正确的方法来获取 Gamepad 对象：
方法一：使用正确的解构赋值语法
如果你希望利用解构赋值的简洁性来获取第一个连接的手柄，应该直接对 navigator.getGamepads() 的返回值（一个类数组）进行解构，而不是对类数组中的单个元素进行解构。
// 获取所有连接的手柄，并将第一个手柄赋值给 gp
const [gp] = navigator.getGamepads();
// 确保 gp 不为 null，因为可能没有手柄连接
if (gp) {
console.log("使用解构赋值获取的第一个手柄ID:", gp.id);
console.log("轴数量:", gp.axes.length);
console.log("按钮数量:", gp.buttons.length);
} else {
console.log("没有手柄连接或第一个槽位为空。");
}这段代码的逻辑是：navigator.getGamepads() 返回一个 Gamepad 对象的“数组”，const [gp] = ... 会从这个数组中取出第一个元素并赋值给 gp。
方法二：不使用解构赋值的传统方式
如果你不需要解构赋值，或者觉得直接索引更直观，可以直接通过索引访问 navigator.getGamepads() 返回的类数组中的元素。
// 直接获取第一个手柄
const gp = navigator.getGamepads()[0];
// 确保 gp 不为 null
if (gp) {
console.log("不使用解构赋值获取的第一个手柄ID:", gp.id);
console.log("轴数量:", gp.axes.length);
console.log("按钮数量:", gp.buttons.length);
} else {
console.log("没有手柄连接或第一个槽位为空。");
}这两种方法都能有效地获取到第一个连接的 Gamepad 对象，并避免了 TypeError。
注意事项与最佳实践
-
处理 null 值： navigator.getGamepads() 返回的数组或类数组中，未连接手柄的槽位会是 null。因此，在访问 gp 的属性（如 gp.axes 或 gp.id）之前，务必检查 gp 是否为 null，以避免 TypeError: Cannot read properties of null。
const [gp] = navigator.getGamepads(); if (gp) { // 检查 gp 是否存在 console.log(gp.axes); } else { console.warn("当前没有可用的游戏手柄。"); } -
动态手柄检测： navigator.getGamepads() 仅反映调用时的手柄状态。为了在手柄连接或断开时做出响应，应使用 gamepadconnected 和 gamepaddisconnected 事件。
window.addEventListener("gamepadconnected", (e) => { console.log("手柄已连接:", e.gamepad.id, "在索引", e.gamepad.index); // 可以在此处初始化手柄相关逻辑 }); window.addEventListener("gamepaddisconnected", (e) => { console.log("手柄已断开:", e.gamepad.id, "在索引", e.gamepad.index); // 可以在此处清理手柄相关逻辑 }); -
在游戏循环中轮询： 在实际的游戏开发中，通常不会只在连接事件中获取手柄状态。为了实时获取手柄的轴（摇杆）和按钮状态，你需要在动画帧或游戏循环中周期性地调用 navigator.getGamepads() 来更新手柄数据。
function gameLoop() { const gamepads = navigator.getGamepads(); for (const gp of gamepads) { if (gp) { // 处理当前手柄的输入 // console.log(`手柄 ${gp.id} 轴0: ${gp.axes[0]}, 按钮0: ${gp.buttons[0].pressed}`); } } requestAnimationFrame(gameLoop); } // 在页面加载后启动游戏循环 // requestAnimationFrame(gameLoop);
总结
在使用 HTML5 Gamepad API 时，理解 navigator.getGamepads() 的返回值类型（一个 Gamepad 对象的类数组）是至关重要的。当使用解构赋值时，应确保对可迭代对象进行解构。错误的 const [gp] = navigator.getGamepads()[0] 会因为尝试解构一个非可迭代的 Gamepad 对象或 null 而导致 TypeError。通过采用正确的解构赋值 const [gp] = navigator.getGamepads() 或直接索引 const gp = navigator.getGamepads()[0]，并结合对 null 值的检查和事件监听机制，可以健壮地开发基于 Gamepad API 的交互应用。
