能力中的 API
WebHID API
发布于
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() 可以从脚本撤销授权,所以「移除设备」按钮不必把用户送去站点设置页就能清掉它。
另请参阅
链接到“另请参阅”一节- WebUSB API,用于非 HID 类的 USB 接口
- Web Serial API
- Web Bluetooth API,用于以 GATT 而非 HID 通信的蓝牙低功耗设备
- WebHID: requestDevice() method(hid.spec.whatwg.org)
- WebHID: HIDDevice open() method(hid.spec.whatwg.org)
- WebKit standards position: WebHID(github.com)
- Connecting to uncommon HID devices(developer.chrome.com)
规范
| 规范 | 状态 |
|---|---|
| WebHID API | WICG 草案 |
| WebHID: requestDevice() method | WHATWG 现行标准 |
| WebHID: HIDDevice open() method | WHATWG 现行标准 |
| WebHID: HIDDeviceRequestOptions dictionary | WHATWG 现行标准 |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| 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 |
- browser-compat-data 未记录 Chrome Android 的支持。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Firefox for Android 的支持。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- browser-compat-data 未记录 Samsung Internet 的支持。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- browser-compat-data 未记录 WebView Android 的支持。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。