大网数据广告活动
Web 标准与前端开发

HID:requestDevice() 方法

· 52CE 我爱测

HID 接口的 **`requestDevice()`** 方法请求请问 HID 设备。

WebHID API

HID 接口的 requestDevice() 方法请求请问 HID 设备。

用户代理将显示一个包含已连接设备列表的权限对话框,并要求用户选择其中一个设备并授予权限。

语法

requestDevice(options)

参数

  • options
    • : 一个对象,包含要与之配对的可能设备的过滤器对象数组。每个过滤器对象可以具有以下属性:
      • vendorId

        • : 一个整数,表示请求的 HID 设备的供应商 ID(即:vendorId)
      • productId

        • : 一个整数,表示请求的 HID 设备的产品 ID(即:productId)
      • usagePage

        • : 一个整数,表示请求设备的 HID 用途中的用途页面组件。顶级集合的用途用于识别设备类型。

          可以在 HID 使用表 文档中找到标准 HID 用途值。

      • usage

        • : 一个整数,表示请求设备的 HID 用途中的用途 ID 组件。

[!NOTE] 设备过滤器用于缩小向用户展示的设备列表。如果没有过滤器,则显示所有连接的设备。当包含一个或多个过滤器时,如果任何过滤器匹配,则包含该设备。为了匹配过滤器,该过滤器中包含的所有规则都必须匹配。

返回值

一个会兑现为与传入的过滤器匹配的已连接 HIDDevice 对象数组的 Promise。

异常

  • 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 });

规范

浏览器兼容性

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。