JS手柄API使用指南与教程

小伙伴们对文章编程感兴趣吗？是否正在学习相关知识点？如果是，那么本文《浏览器JS手柄API使用教程》，就很适合你，本篇文章讲解的知识点主要包括。在之后的文章中也会多多分享相关知识点，希望对大家的知识积累有所帮助！

答案：通过监听gamepadconnected和gamepaddisconnected事件检测手柄连接状态，并利用requestAnimationFrame周期性调用navigator.getGamepads()获取手柄输入数据，结合事件监听与状态轮询实现手柄交互。

现代浏览器确实提供了JavaScript游戏手柄API，允许网页应用直接与用户的游戏手柄进行交互，获取按钮按下、摇杆倾斜等输入数据，为基于Web的游戏或互动体验开辟了新的可能性。

解决方案

要利用浏览器中的JS游戏手柄API，核心在于监听手柄连接/断开事件，并周期性地读取手柄状态。

首先，你需要监听gamepadconnected和gamepaddisconnected事件。这些事件会在手柄插入或拔出时触发，让你知道哪个手柄可用或不可用。通常，我们会维护一个已连接手柄的列表。

let gamepads = {}; // 用于存储已连接的手柄

window.addEventListener("gamepadconnected", (event) => {
    const gamepad = event.gamepad;
    console.log(`游戏手柄 ${gamepad.index}: ${gamepad.id} 已连接.`);
    gamepads[gamepad.index] = gamepad;
    // 可以在这里启动游戏循环或UI更新
    startGamepadPolling();
});

window.addEventListener("gamepaddisconnected", (event) => {
    const gamepad = event.gamepad;
    console.log(`游戏手柄 ${gamepad.index}: ${gamepad.id} 已断开.`);
    delete gamepads[gamepad.index];
    // 检查是否还有其他手柄，如果没有，可以停止游戏循环
    if (Object.keys(gamepads).length === 0) {
        stopGamepadPolling();
    }
});

然后，关键在于如何获取手柄的实时输入。浏览器不会自动推送手柄状态更新，你需要主动去“轮询”它。最推荐的方式是结合requestAnimationFrame来创建一个游戏循环，在每一帧中获取最新的手柄数据。

let animationFrameId = null;

function startGamepadPolling() {
    if (animationFrameId !== null) return; // 避免重复启动

    function pollGamepads() {
        // 每次调用 getGamepads() 都会返回最新的手柄状态数组
        const currentGamepads = navigator.getGamepads();
        for (const index in gamepads) {
            const gamepad = currentGamepads[index];
            if (gamepad) {
                // 处理手柄输入
                handleGamepadInput(gamepad);
            }
        }
        animationFrameId = requestAnimationFrame(pollGamepads);
    }
    animationFrameId = requestAnimationFrame(pollGamepads);
}

function stopGamepadPolling() {
    if (animationFrameId !== null) {
        cancelAnimationFrame(animationFrameId);
        animationFrameId = null;
    }
}

function handleGamepadInput(gamepad) {
    // 示例：检测第一个按钮（通常是A/X按钮）是否被按下
    if (gamepad.buttons[0] && gamepad.buttons[0].pressed) {
        console.log(`手柄 ${gamepad.id} 的按钮 0 被按下！`);
    }

    // 示例：检测左摇杆X轴（通常是0）的输入
    const leftStickX = gamepad.axes[0];
    if (Math.abs(leftStickX) > 0.1) { // 设定一个死区，避免轻微漂移
        console.log(`手柄 ${gamepad.id} 左摇杆X轴: ${leftStickX}`);
    }

    // 你可以根据游戏逻辑，将这些输入映射到角色的移动、动作等
}

通过这样的机制，你就能在网页中实时响应游戏手柄的输入了。对我来说，这种低层级的控制方式虽然需要开发者自己处理很多细节，但它也提供了极大的灵活性，能让你构建出非常精细的交互体验。

如何检测和连接游戏手柄，并开始获取输入？

检测和连接游戏手柄，在Web环境中，核心就是利用浏览器提供的Gamepad API接口。我个人觉得，理解这个过程的关键在于两点：事件监听和状态轮询。

首先，当用户将游戏手柄插入计算机或通过蓝牙连接时，浏览器会触发一个gamepadconnected事件。这是一个非常重要的信号，因为它告诉你有一个新的输入设备可用了。在这个事件的回调函数里，你会得到一个Gamepad对象，它包含了手柄的基本信息，比如它的ID（通常会包含厂商和产品信息）、索引（这是浏览器分配给它的唯一标识符，从0开始）、以及最重要的——它的按钮和轴（摇杆）的数量。我通常会把这个Gamepad对象存储在一个全局的映射或数组里，以便后续通过其索引快速访问。

// 示例：在gamepadconnected事件中存储手柄
let activeGamepads = new Map(); // 使用Map更灵活

window.addEventListener("gamepadconnected", (event) => {
    const gp = event.gamepad;
    console.log(`Gamepad connected at index ${gp.index}: ${gp.id}. ${gp.buttons.length} buttons, ${gp.axes.length} axes.`);
    activeGamepads.set(gp.index, gp);
    // 此时，你可以启动一个游戏循环来持续读取这个手柄的状态
    if (!pollingActive) { // 确保只启动一次轮询
        startPolling();
    }
});

window.addEventListener("gamepaddisconnected", (event) => {
    const gp = event.gamepad;
    console.log(`Gamepad disconnected from index ${gp.index}: ${gp.id}.`);
    activeGamepads.delete(gp.index);
    if (activeGamepads.size === 0) {
        stopPolling(); // 如果所有手柄都断开了，停止轮询以节省资源
    }
});

光连接上还不够，你需要知道手柄上发生了什么。这就是“获取输入”的部分。与键盘或鼠标事件不同，游戏手柄的按钮和摇杆状态不会主动触发事件（除了连接/断开）。你需要自己去“问”浏览器手柄的最新状态是什么。这个“问”的动作就是通过navigator.getGamepads()方法实现的。这个方法会返回一个数组，其中包含了所有当前已连接手柄的最新快照。

我发现最有效的策略是使用requestAnimationFrame来创建一个持续的循环（也就是所谓的“游戏循环”）。在每一帧中，你调用navigator.getGamepads()，然后遍历返回的数组，找到你感兴趣的手柄，读取它的buttons和axes属性。

let pollingActive = false;
let animationFrameId = null;

function startPolling() {
    pollingActive = true;
    function gameLoop() {
        const gamepadsSnapshot = navigator.getGamepads();
        activeGamepads.forEach((gp, index) => {
            const latestGp = gamepadsSnapshot[index];
            if (latestGp) { // 确保手柄仍然存在
                // 处理按钮状态
                latestGp.buttons.forEach((button, btnIndex) => {
                    if (button.pressed) {
                        // console.log(`Gamepad ${latestGp.id} Button ${btnIndex} pressed.`);
                        // 触发游戏中的相应动作
                    }
                });
                // 处理摇杆状态
                latestGp.axes.forEach((axisValue, axisIndex) => {
                    if (Math.abs(axisValue) > 0.1) { // 设定死区
                        // console.log(`Gamepad ${latestGp.id} Axis ${axisIndex}: ${axisValue}`);
                        // 映射到角色移动等
                    }
                });
            }
        });
        animationFrameId = requestAnimationFrame(gameLoop);
    }
    animationFrameId = requestAnimationFrame(gameLoop);
}

function stopPolling() {
    pollingActive = false;
    if (animationFrameId) {
        cancelAnimationFrame(animationFrameId);
        animationFrameId = null;
    }
}

通过这种事件监听加循环轮询的模式，你就能有效地检测到手柄，并在每一帧中获取其最新的输入数据了。这套机制说起来有点像“拉取”而不是“推送”，但对于游戏这种需要高频率更新状态的应用来说，这种模式反而更可控、更高效。

游戏手柄的输入数据结构是怎样的？

理解游戏手柄的输入数据结构是处理手柄交互的基础。当我第一次接触这个API时，我发现它非常直观，但又足够灵活。每个Gamepad对象主要包含几个关键属性，它们共同描绘了手柄的当前状态。

一个Gamepad对象的核心属性包括：

• id: 这是一个字符串，通常包含了手柄的厂商和产品信息，比如"Xbox 360 Controller (XInput STANDARD GAMEPAD)"或"Wireless Controller (STANDARD GAMEPAD)"。它对于识别特定类型的手柄很有用，尤其是在处理兼容性问题时。
• index: 一个整数，表示浏览器为这个手柄分配的唯一索引。这是它在navigator.getGamepads()返回数组中的位置，通常从0开始。
• connected: 一个布尔值，表示手柄当前是否连接。
• timestamp: 一个数字，表示上次更新手柄数据的时间戳。这对于判断数据是否新鲜或进行时间同步很有用。
• mapping: 一个字符串，通常是"standard"或空字符串。如果手柄遵循“标准游戏手柄布局”（Standard Gamepad Layout），则为"standard"。这个布局定义了按钮和轴的通用映射，这在跨平台和设备兼容性方面非常重要。
• buttons: 这是一个数组，数组中的每个元素都是一个GamepadButton对象，代表手柄上的一个按钮。GamepadButton对象有三个属性：
  • pressed (布尔值): 如果按钮当前被按下，则为true。
  • touched (布尔值): 如果按钮当前被触摸（适用于一些触摸敏感的按钮），则为true。
  • value (数字): 按钮的压力值，通常在0.0（未按下）到1.0（完全按下）之间。这对于支持模拟压力的按钮（比如一些扳机键）非常有用。 标准布局通常将A/X、B/圆、X/方、Y/三角等主按钮映射到buttons[0]到buttons[3]，肩部按钮、扳机、选择、开始等也都有对应的索引。
• axes: 这是一个数组，数组中的每个元素都是一个数字，代表一个摇杆或D-pad（方向键）轴的当前位置。值通常在-1.0到1.0之间。
  • -1.0通常表示最左或最上。
  • 1.0通常表示最右或最下。
  • 0.0表示中心位置。 标准布局通常将左摇杆的X轴映射到axes[0]，Y轴映射到axes[1]；右摇杆的X轴映射到axes[2]，Y轴映射到axes[3]。

举个例子，如果我想检测Xbox手柄的A按钮是否被按下，我会查看gamepad.buttons[0].pressed。如果我想获取左摇杆的水平方向输入，我会读取gamepad.axes[0]的值。这种结构简洁明了，让我能够快速地将手柄输入映射到我的游戏逻辑中。虽然不同手柄的按钮和轴的物理布局可能不同，但通过mapping: "standard"这个提示，我们可以对大多数主流手柄进行相对统一的处理，这大大简化了开发工作。

如何处理不同类型游戏手柄的兼容性问题？

处理不同类型游戏手柄的兼容性问题，这绝对是Web Gamepad API开发中最让人头疼，但也最能体现开发者智慧的地方。说实话，虽然有“标准游戏手柄布局”（Standard Gamepad Layout），但现实世界远比标准复杂。你可能会遇到Xbox手柄、PlayStation手柄、各种通用USB手柄，它们在按钮和轴的索引映射上，有时会让你抓狂。

我的经验告诉我，解决这个问题有几个层次的策略：

1. 依赖Gamepad.mapping属性： 这是最直接也是最理想的情况。如果gamepad.mapping的值是"standard"，那么恭喜你，这个手柄的按钮和轴映射遵循W3C定义的标准布局。这意味着buttons[0]通常是A/X按钮，axes[0]是左摇杆的X轴等等。对于这些手柄，你可以直接使用一套固定的索引来处理输入。

   if (gamepad.mapping === "standard") {
       // A/X button
       if (gamepad.buttons[0].pressed) { /* ... */ }
       // Left stick X-axis
       const leftStickX = gamepad.axes[0];
   }

   然而，并非所有手柄都会报告"standard"映射，有些手柄可能报告空字符串或者其他非标准的值。这时，你就需要更高级的策略了。

2. 通过Gamepad.id进行设备特定映射： 当mapping不是"standard"时，gamepad.id就成了你的救星。id字符串通常包含了手柄的品牌和型号信息。你可以建立一个映射表，根据id来为不同的手柄定义一套特定的按钮和轴索引。

   const customMappings = {
       "VendorX ProductY Gamepad": {
           actionButton: 2, // 假设这个手柄的“动作”按钮是索引2
           jumpButton: 1,
           leftStickX: 3 // 假设左摇杆X轴是索引3
       },
       "Another Generic Gamepad": { /* ... */ }
   };
   
   let effectiveMapping = {};
   if (gamepad.mapping === "standard") {
       effectiveMapping = { actionButton: 0, jumpButton: 1, leftStickX: 0 /* ... */ };
   } else if (customMappings[gamepad.id]) {
       effectiveMapping = customMappings[gamepad.id];
   } else {
       // Fallback for unknown non-standard gamepads, maybe warn user
       console.warn(`Unknown gamepad ID: ${gamepad.id}. Using default (potentially incorrect) mapping.`);
       effectiveMapping = { actionButton: 0, jumpButton: 1, leftStickX: 0 /* ... */ }; // 或者提示用户进行配置
   }
   
   if (gamepad.buttons[effectiveMapping.actionButton].pressed) { /* ... */ }

   这需要你手动收集和测试各种手柄，维护一个映射数据库，工作量不小，但效果最可靠。

3. 提供用户自定义配置： 这是最用户友好的方式，也是我个人最推荐的终极解决方案。在你的应用中提供一个“手柄配置”界面，允许用户通过按下按钮或移动摇杆来告诉你的应用“这个按钮是跳跃”、“那个摇杆是移动”。

   • 按钮映射： 当用户点击“配置跳跃按钮”时，监听所有按钮的按下事件，第一个被按下的按钮就是跳跃按钮。
   • 轴映射： 对于摇杆，可以提示用户“请向左移动左摇杆”，然后检测哪个轴的值变化最大，并记录下来。 将这些用户定义的映射存储在localStorage中，下次用户连接手柄时自动加载。这不仅解决了兼容性问题，还提升了用户体验，让他们能按照自己的习惯来玩游戏。

4. 利用社区或库： 有些开源库或社区项目可能已经收集了大量手柄的映射数据，你可以考虑集成它们，而不是从头开始构建自己的映射表。这可以大大减少你的开发负担。

总的来说，处理手柄兼容性是一个从“理想标准”到“现实妥协”再到“用户定制”的渐进过程。从简单的mapping属性开始，如果不够，就深入到id层面做设备特定适配，最终，为用户提供自定义能力，才能真正做到万无一失。这中间的挑战在于如何平衡开发成本和用户体验，但当你看到用户用自己的手柄流畅地玩你开发的Web游戏时，那种成就感是无与伦比的。

好了，本文到此结束，带大家了解了《JS手柄API使用指南与教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！