跳转到内容

能力中的 API

WebHID API

发布于

有限可用不支持的浏览器: Chrome (Android)、Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)WICG 草案

navigator.hid.requestDevice() 让用户在浏览器选择器中授权 PWA 访问已连接的人机接口设备(HID)。选择器按传入的过滤器列出设备,用户授权后返回相应的 HIDDevice 对象。打开设备后,PWA 用 inputreport 事件接收输入报告,以字节缓冲区发送输出报告和特征报告。这种方式可用于宏键盘、游戏手柄、条码扫描器,以及用 USB 或蓝牙 HID 协议通信的实验仪器。

支持仅限桌面 Chromium:Windows、macOS、Linux 与 ChromeOS 上的 Chrome 89 和 Edge 89 实现了 HID、HIDDevice、requestDevice() 与 getDevices();Chrome 100 加入 HIDDevice.forget(),Chrome 131 在专用 worker 中暴露 navigator.hid(BCD api.HID、api.HID.worker_support)。Android 版 Chrome、Android WebView、Firefox 与 Safari 均无支持,WebKit 已提交正式的「反对」立场(standards-positions #510)。

navigator.hid.requestDevice(options)
navigator.hid.getDevices()
device.open()
device.close()
device.forget()
device.sendReport(reportId, data)
device.sendFeatureReport(reportId, data)
device.receiveFeatureReport(reportId)

requestDevice() 与 getDevices() 返回 Promise<sequence<HIDDevice>>;用户关闭选择器时 requestDevice() 以空序列兑现而不是拒绝。open()、close()、forget()、sendReport() 与 sendFeatureReport() 返回 Promise<undefined>;receiveFeatureReport() 返回 Promise<DataView>,其首字节可能是报告 ID。navigator.hid 标注为 [SecureContext],requestDevice() 还要求在带瞬时用户激活的 Window 全局对象中调用。每个 HIDDevice 暴露 opened、vendorId、productId、productName 与 collections,并触发 inputreport(HIDInputReportEvent,带 device、reportId、data);navigator.hid 对已授权设备触发 connect 与 disconnect(HIDConnectionEvent,带 device)。

requestDevice() 接受一个 HIDDeviceRequestOptions 字典。

成员 类型 必填 说明
filters sequence<HIDDeviceFilter> 是 匹配任一过滤器的设备会被列出;[] 列出浏览器未封禁的全部已连接 HID 设备。
exclusionFilters sequence<HIDDeviceFilter> 否 匹配其中任一项的设备即使匹配 filters 也会被隐藏。给出时必须非空。

HIDDeviceFilter 的每个成员都是可选的,但只有当 productId 与 vendorId 同时出现、usage 与 usagePage 同时出现时过滤器才有效。

成员 类型 说明
vendorId unsigned long USB-IF 厂商 ID,例如 Logitech 为 0x046d。
productId unsigned short 产品 ID;需要同时给出 vendorId。
usagePage unsigned short 顶层集合的 HID usage page,例如 0x0001 为 Generic Desktop,0xff00 及以上为厂商自定义页。
usage unsigned short usagePage 内的 usage ID;需要同时给出 usagePage。

sendReport()、sendFeatureReport() 与 receiveFeatureReport() 接受 reportId(octet,接口不使用报告 ID 时为 0);两个发送方法还接受 BufferSource 类型的 data,即不含 ID 字节的报告载荷。

出现下列情况之一时,requestDevice() 与 getDevices() 在任何选择器出现之前即拒绝。

异常 条件
SecurityError 文档不被允许使用 hid Permissions Policy 特性,或(仅 requestDevice())调用时没有瞬时用户激活。
NotSupportedError requestDevice() 在非 Window 的全局对象(如 worker)中被调用。
TypeError filters 或 exclusionFilters 中有无效过滤器(只有 productId 没有 vendorId,或只有 usage 没有 usagePage),或 exclusionFilters 给出但为空。

HIDDevice 各方法的拒绝条件如下。

方法 异常 条件
open() InvalidStateError 设备状态不是 "closed"(已打开、正在打开或已遗忘)。
open() NetworkError 操作系统拒绝打开设备。
close() 无 正常兑现;任何挂起的 sendReport() 或特征报告 Promise 以 AbortError 拒绝。
forget() InvalidStateError Chromium:该设备上另一个 open() 或 forget() 调用仍在进行。
sendReport()、sendFeatureReport()、receiveFeatureReport() InvalidStateError 设备不处于 "opened" 状态。
同上三个 TypeError 接口使用报告 ID 却传了 0,或接口不使用报告 ID 却传了非零值。
同上三个 NotAllowedError 该报告在浏览器的封禁列表上(例如受保护的键盘或 FIDO 集合上的报告)。
同上三个 NetworkError 操作系统写入或读取报告失败。

浏览器会丢弃封禁的输入报告,不触发 inputreport,也不报异常。

先检查 navigator.hid 是否存在。Firefox、Safari 和 Android 没有这个属性,需要提供回退方案。

按厂商 ID 过滤,选择器只列出该厂商的设备;取第一台授权设备并打开。调用必须放在 click 处理函数内。没有 WebHID 时,处理函数改为提示用户使用厂商的桌面工具。

const LOGITECH = 0x046d;
document.querySelector('#pair').addEventListener('click', async () => {
const note = document.querySelector('#hid-note');
if (!('hid' in navigator)) {
note.textContent = '此浏览器无法与 HID 设备通信,请用厂商工具进行配置。';
return;
}
const [device] = await navigator.hid.requestDevice({ filters: [{ vendorId: LOGITECH }] });
if (!device) return; // 选择器被关闭:返回空数组,不是错误
if (!device.opened) await device.open();
note.textContent = `已连接 ${device.productName}(${device.vendorId.toString(16)}:${device.productId.toString(16)})`;
});

用户关闭选择器时 requestDevice() 以空数组兑现,所以解构后判断 device 就能覆盖取消的情况,不需要 try/catch。

open() 之后,设备发送的每份报告都以 inputreport 事件到达,data 是载荷的 DataView。处理函数把两字节的厂商报告解码成旋钮位置和按键位图。报告布局由设备的报告描述符决定,运行时可用 device.collections 查看。

function listenToDial(device, onChange) {
if (!('hid' in navigator)) return () => {};
const handler = (event) => {
if (event.reportId !== 0x01) return;
const position = event.data.getUint8(0);
const buttons = event.data.getUint8(1);
onChange({ position, pressed: (buttons & 0x01) !== 0 });
};
device.addEventListener('inputreport', handler);
return () => device.removeEventListener('inputreport', handler);
}

event.data 不含报告 ID 字节,报告 ID 单独放在 event.reportId 中。设备接口不使用报告编号时,这个值为 0。

授权在刷新后仍然有效,所以 getDevices() 无需弹窗也无需手势就能返回此前授权的设备。配合 connect 与 disconnect 事件,设备在页面打开期间拔出再插入时,可以重新打开它。

async function restoreDevices(onDevice, onGone) {
if (!('hid' in navigator)) return;
for (const device of await navigator.hid.getDevices()) {
await device.open();
onDevice(device);
}
navigator.hid.addEventListener('connect', async ({ device }) => {
await device.open();
onDevice(device);
});
navigator.hid.addEventListener('disconnect', ({ device }) => onGone(device));
}

forget() 可以从脚本撤销授权,所以「移除设备」按钮不必把用户送去站点设置页就能清掉它。

规范

规范状态
WebHID APIWICG 草案
WebHID: requestDevice() methodWHATWG 现行标准
WebHID: HIDDevice open() methodWHATWG 现行标准
WebHID: HIDDeviceRequestOptions dictionaryWHATWG 现行标准
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持89高来源—
Chrome (Android)#不支持—高来源1
Edge (Desktop)#支持89高来源2
Firefox (Desktop)#不支持—高来源3
Firefox (Android)#不支持—高来源45
Safari (macOS)#不支持—高来源6
Safari (iOS)#不支持—高来源78
Samsung Internet#不支持—高来源910
WebView (Android)#不支持—高来源1112
  1. browser-compat-data 未记录 Chrome Android 的支持。
  2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  3. browser-compat-data 未记录 Firefox 的支持。
  4. browser-compat-data 未记录 Firefox for Android 的支持。
  5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  6. browser-compat-data 未记录 Safari 的支持。
  7. browser-compat-data 未记录 iOS 版 Safari 的支持。
  8. 由 browser-compat-data 镜像自 Safari 的数据推导。
  9. browser-compat-data 未记录 Samsung Internet 的支持。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  11. browser-compat-data 未记录 WebView Android 的支持。
  12. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/web-hid.json · 全球使用占比: 39 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)