深入探索 Gamepad API：为网页注入游戏手柄的互动能力

原创

泯泷、

发布于 2025-01-27 11:17:16

1400

现代 Web 技术的飞速发展让网页交互突破了传统键盘和鼠标的限制。Gamepad API 是其中的一个强大工具，它为网页带来了原生支持游戏控制器的能力。本文将通过详细的实践案例，向您展示如何利用 Gamepad API 构建更有趣、更互动的网页应用。

什么是 Gamepad API？

Gamepad API 是一组浏览器接口，允许开发者访问用户连接的游戏手柄设备的状态信息。这些信息包括：

按钮状态：检测按钮是否被按下，以及按下的强度（支持压力感应）。
轴输入：获取操纵杆的方向和位置。
手柄连接事件：动态监听手柄的连接与断开。

这项技术广泛应用于游戏开发，但它的潜力远不限于此，还可以用于数据可视化、虚拟现实控制等场景。

Gamepad API 快速入门

检测手柄的连接和断开

我们可以通过 gamepadconnected 和 gamepaddisconnected 事件，监控手柄的连接状态：

window.addEventListener("gamepadconnected", (event) => {
    const gamepad = event.gamepad;
    console.log(`手柄已连接：${gamepad.id}`);
});

window.addEventListener("gamepaddisconnected", (event) => {
    console.log(`手柄已断开：${event.gamepad.id}`);
});

提示：浏览器会在手柄连接后为其分配一个索引，通过索引可以唯一标识设备。

获取手柄数据

navigator.getGamepads() 返回一个包含所有连接手柄的数组。以下是一个简单的实时获取手柄状态的示例：

function logGamepadState() {
    const gamepads = navigator.getGamepads();
    if (gamepads[0]) {
        const gamepad = gamepads[0];
        
        // 按钮状态
        gamepad.buttons.forEach((button, index) => {
            if (button.pressed) {
                console.log(`按钮 ${index} 被按下`);
            }
        });

        // 轴状态
        gamepad.axes.forEach((axis, index) => {
            console.log(`轴 ${index} 值: ${axis.toFixed(2)}`);
        });
    }
    requestAnimationFrame(logGamepadState);
}

logGamepadState();

实践案例 1：创建一个手柄控制的虚拟方向盘

在这个案例中，我们将使用手柄的操纵杆模拟一个简单的虚拟方向盘。

HTML 结构

创建一个基础的 HTML 页面，包含一个指针：

<div id="wheel" style="width: 200px; height: 200px; border: 2px solid black; border-radius: 50%; position: relative;">
    <div id="pointer" style="width: 10px; height: 100px; background: red; position: absolute; left: 95px; transform-origin: bottom center;"></div>
</div>

JavaScript 控制逻辑

通过获取左操纵杆的 X 轴值，将指针的角度与操纵杆的输入值关联：

const pointer = document.getElementById("pointer");

function updateWheel() {
    const gamepads = navigator.getGamepads();
    if (gamepads[0]) {
        const xAxis = gamepads[0].axes[0]; // 左操纵杆的X轴
        const rotation = xAxis * 90; // 将 -1 到 1 的范围映射到 -90° 到 90°
        pointer.style.transform = `rotate(${rotation}deg)`;
    }
    requestAnimationFrame(updateWheel);
}

updateWheel();

实践案例 2：用手柄控制一个简易游戏角色

此案例展示如何通过手柄控制页面上的一个方块移动。

HTML 结构

<div id="character" style="width: 50px; height: 50px; background: blue; position: absolute; top: 200px; left: 200px;"></div>

JavaScript 控制逻辑

使用手柄的操纵杆和按钮控制角色的移动：

const character = document.getElementById("character");
let posX = 200, posY = 200;

function updateCharacter() {
    const gamepads = navigator.getGamepads();
    if (gamepads[0]) {
        const xAxis = gamepads[0].axes[0]; // 左操纵杆的X轴
        const yAxis = gamepads[0].axes[1]; // 左操纵杆的Y轴

        // 更新角色位置
        posX += xAxis * 5; // 调整速度
        posY += yAxis * 5;
        character.style.left = `${posX}px`;
        character.style.top = `${posY}px`;

        // 检测特定按钮是否被按下
        if (gamepads[0].buttons[0].pressed) {
            character.style.background = "red"; // 按下按钮改变颜色
        } else {
            character.style.background = "blue";
        }
    }
    requestAnimationFrame(updateCharacter);
}

updateCharacter();

实践案例 3：多手柄支持

如果你的项目需要支持多个手柄，可以通过遍历所有连接设备实现：

function logAllGamepads() {
    const gamepads = navigator.getGamepads();
    gamepads.forEach((gamepad, index) => {
        if (gamepad) {
            console.log(`手柄 ${index} 状态:`);
            gamepad.buttons.forEach((button, buttonIndex) => {
                if (button.pressed) {
                    console.log(`手柄 ${index} 的按钮 ${buttonIndex} 被按下`);
                }
            });
        }
    });
    requestAnimationFrame(logAllGamepads);
}

logAllGamepads();