WebHID API能否读取键鼠底层事件？事件监听失效及替代方案问询

1. WebHID API能否读取键鼠底层事件？还有哪些Web技术可获取底层输入事件？ #

WebHID API可以读取鼠标或键盘的底层事件，它的核心特性就是允许Web应用绕过浏览器默认输入处理逻辑，直接获取设备的原始HID输入报告，包括按键按下、鼠标移动/点击的原始数据。

Web端可用于获取输入事件的其他技术：

• DOM原生事件：如keydown/keyup、mousedown/mousemove等，但这类事件是浏览器处理后的标准化事件，并非底层原始数据，且受浏览器焦点、事件冒泡等规则限制。
• Pointer Lock API：可以锁定鼠标指针，获取鼠标的相对移动数据（适合游戏等需要精准控制的场景），虽不是直接读取设备底层报告，但能突破浏览器默认的鼠标移动限制。
• WebUSB API：如果键鼠设备支持直接USB访问（部分自定义设备），可通过WebUSB直接与设备通信获取底层数据，但通用性不如WebHID。
• Gamepad API：针对游戏手柄类设备，但部分多功能键鼠会被识别为游戏设备，也可通过此API获取输入。

2. 选择键鼠后EventListener未触发的问题排查与解决 #

出现该问题通常有以下原因及对应解决方法：

原因1：未指定正确的设备过滤规则 #

示例代码中filters为空数组，会列出所有HID设备，可能选中非标准键鼠或用法页不匹配的设备。标准键鼠的HID用法页：

• 键盘：Usage Page 0x01，Usage 0x06
• 鼠标：Usage Page 0x01，Usage 0x02

修改requestDevice的过滤规则，确保只列出目标设备：

const devices = await navigator.hid.requestDevice({
  filters: [
    { usagePage: 0x01, usage: 0x06 }, // 键盘
    { usagePage: 0x01, usage: 0x02 }  // 鼠标
  ]
});

原因2：浏览器安全上下文限制 #

WebHID API仅支持HTTPS环境（localhost除外），HTTP环境下API会被禁用，导致设备无法正常监听事件。

原因3：设备被系统或其他程序独占 #

部分系统或应用（如游戏、远程桌面软件）会独占键鼠设备，导致WebHID无法获取输入报告，关闭这类程序后重试即可。

原因4：输入报告解析或监听时机问题 #

• 确保addEventListener在device.open()完成后设置（示例代码逻辑正确，但需确认await device.open()无异常）。
• 不同键鼠的HID输入报告格式可能不同，可通过Chrome的chrome://device-log查看设备输入报告日志，确认数据格式后再处理。

原因5：浏览器兼容性问题 #

WebHID目前仅在Chrome、Edge等Chromium内核浏览器支持，Firefox、Safari暂未支持，需确认浏览器版本符合要求。

3. Web浏览器获取鼠标底层事件的方案 #

首选方案：WebHID API #

按照优化后的代码，指定鼠标过滤规则，正确监听inputreport事件并解析原始输入报告（通常包含相对X/Y移动、按键状态等数据）。修改后的鼠标示例代码：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8" />
    <title>WebHID 鼠标示例</title>
</head>
<body>
    <button id="requestDeviceButton">请求HID鼠标设备</button>

    <script>
        document.addEventListener("DOMContentLoaded", () => {
            const requestDeviceButton = document.getElementById("requestDeviceButton");

            if ("hid" in navigator) {
                requestDeviceButton.addEventListener("click", async () => {
                    try {
                        const devices = await navigator.hid.requestDevice({
                            filters: [{ usagePage: 0x01, usage: 0x02 }] // 仅匹配鼠标
                        });

                        for (const device of devices) {
                            await device.open();
                            device.addEventListener("inputreport", (event) => {
                                const data = new Uint8Array(event.data.buffer);
                                // 解析鼠标数据：data[0]为按键状态，data[1]为X偏移，data[2]为Y偏移
                                const buttons = data[0];
                                const deltaX = data[1];
                                const deltaY = data[2];
                                console.log(`鼠标移动：X=${deltaX}, Y=${deltaY}，按键状态：${buttons}`);
                            });
                            console.log("已连接鼠标设备：", device.productName);
                        }
                    } catch (error) {
                        console.error("打开鼠标设备失败：", error);
                    }
                });
            } else {
                console.error("当前浏览器不支持WebHID API");
            }
        });
    </script>
</body>
</html>

替代方案：Pointer Lock API #

如果不需要原始设备报告，仅需精准的鼠标移动数据，可使用Pointer Lock API：

document.addEventListener("mousemove", (e) => {
    if (document.pointerLockElement === document.body) {
        console.log(`相对移动：X=${e.movementX}, Y=${e.movementY}`);
    }
});

// 请求锁定鼠标
document.body.addEventListener("click", () => {
    document.body.requestPointerLock();
});

跨端方案（非纯Web） #

如果需要更底层的访问，可使用Electron等框架，直接调用Node.js的系统API或第三方库（如node-hid）获取键鼠底层事件，但这不属于纯Web范畴。

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