HID:requestDevice() 方法
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
HID
接口的 requestDevice()
方法请求请问 HID 设备。
用户代理将显示一个包含已连接设备列表的权限对话框,并要求用户选择其中一个设备并授予权限。
语法
requestDevice(options)
参数
options
-
一个对象,包含要与之配对的可能设备的过滤器对象数组。每个过滤器对象可以具有以下属性:
vendorId
可选-
一个整数,表示请求的 HID 设备的供应商 ID(即:vendorId)
productId
可选-
一个整数,表示请求的 HID 设备的产品 ID(即:productId)
usagePage
可选-
一个整数,表示请求设备的 HID 用途中的用途页面组件。顶级集合的用途用于识别设备类型。
可以在 HID 使用表 文档中找到标准 HID 用途值。
usage
可选-
一个整数,表示请求设备的 HID 用途中的用途 ID 组件。
备注: 设备过滤器用于缩小向用户展示的设备列表。如果没有过滤器,则显示所有连接的设备。当包含一个或多个过滤器时,如果任何过滤器匹配,则包含该设备。为了匹配过滤器,该过滤器中包含的所有规则都必须匹配。
返回值
异常
SecurityError
DOMException
-
如果页面不允许访问 HID 功能,则会抛出此异常。
安全性
需要瞬态用户激活。用户必须与页面或 UI 元素进行交互,才能使此功能正常工作。
示例
匹配具有所有四个过滤器规则的设备
在以下示例中,请求一个具有供应商 ID 0xABCD
、产品 ID 0x1234
、用途页面 0x0C
和用途 ID 0x01
的 HID 设备。只有匹配所有这些规则的设备才会显示。
let requestButton = document.getElementById("request-hid-device");
requestButton.addEventListener("click", async () => {
let device;
try {
const devices = await navigator.hid.requestDevice({
filters: [
{
vendorId: 0xabcd,
productId: 0x1234,
usagePage: 0x0c,
usage: 0x01,
},
],
});
device = devices[0];
} catch (error) {
console.log("发生错误。");
}
if (!device) {
console.log("没有选择设备。");
} else {
console.log(`HID:${device.productName}`);
}
});
包含两个过滤器的示例
下一个示例包含了两个过滤器。如果设备匹配其中任何一个过滤器,它们将被显示出来。
// 过滤具有 Nintendo Switch Joy-Con USB 供应商/产品 ID 的设备。
const filters = [
{
vendorId: 0x057e, // 任天堂株式会社(Nintendo Co., Ltd)
productId: 0x2006, // Joy-Con 左手柄
},
{
vendorId: 0x057e, // 任天堂株式会社(Nintendo Co., Ltd)
productId: 0x2007, // Joy-Con 右手柄
},
];
// 提示用户选择一个 Joy-Con 设备。
const [device] = await navigator.hid.requestDevice({ filters });
规范
Specification |
---|
WebHID API # dom-hid-requestdevice |
浏览器兼容性
BCD tables only load in the browser