HTML5 Gamepad API：正确获取手柄对象与解构赋值陷阱解析

本文深入探讨了在使用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() 返回值的处理方式。

1. navigator.getGamepads()[0] 的含义： 这段代码尝试直接访问 getGamepads() 返回的类数组的第一个元素。这个元素本身是一个 Gamepad 对象（如果手柄已连接）或 null（如果第一个槽位没有手柄）。
2. 解构赋值 const [gp] = ... 的要求： 数组解构赋值 [variable] = iterable 语法要求等号右侧的值必须是一个可迭代对象（如数组、字符串、Map、Set等）。
3. 问题所在： navigator.getGamepads()[0] 返回的是一个 Gamepad 对象或 null。Gamepad 对象本身不是一个可迭代对象，null 更不是。因此，尝试将一个非可迭代对象进行解构赋值，就会导致 TypeError。

正确获取 Gamepad 对象的方法

为了避免上述 TypeError，我们可以采用以下两种正确的方法来获取 Gamepad 对象：

方法一：使用正确的解构赋值语法

如果你希望利用解构赋值的简洁性来获取第一个连接的手柄，应该直接对 navigator.getGamepads() 的返回值（一个类数组）进行解构，而不是对类数组中的单个元素进行解构。

即构数智人

即构数智人是由即构科技推出的AI虚拟数字人视频创作平台，支持数字人形象定制、短视频创作、数字人直播等。

36

查看详情

// 获取所有连接的手柄，并将第一个手柄赋值给 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。

注意事项与最佳实践

1. 处理 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("当前没有可用的游戏手柄。");
   }

   登录后复制

2. 动态手柄检测： 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);
       // 可以在此处清理手柄相关逻辑
   });

   登录后复制

3. 在游戏循环中轮询： 在实际的游戏开发中，通常不会只在连接事件中获取手柄状态。为了实时获取手柄的轴（摇杆）和按钮状态，你需要在动画帧或游戏循环中周期性地调用 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 的交互应用。

以上就是HTML5 Gamepad API：正确获取手柄对象与解构赋值陷阱解析的详细内容，更多请关注php中文网其它相关文章！