chrome.hid

说明

使用 chrome.hid API 与已连接的 HID 设备互动。此 API 可在应用上下文中提供对 HID 操作的访问权限。借助此 API，应用可以充当硬件设备的驱动程序。此 API 生成的错误通过设置 runtime.lastError 并执行函数的常规回调来报告。在这种情况下，回调的常规参数将处于未定义状态。

权限

hid

类型

DeviceFilter

属性

  • productId

    number 可选

    设备产品 ID，仅在供应商 ID 匹配时检查。

  • 使用量

    number 可选

    HID 用途标识符，仅在 HID 用途页面匹配时进行检查。

  • usagePage

    number 可选

    HID 用途页面标识符。

  • vendorId

    number 可选

    设备供应商 ID。

GetDevicesOptions

属性

  • 过滤器

    DeviceFilter[] 可选

    系统将返回与任何给定过滤条件匹配的设备。如果过滤条件列表为空，则会返回应用有权访问的所有设备。

  • productId

    number 可选

    已弃用

    相当于设置 DeviceFilter.productId。

  • vendorId

    number 可选

    已弃用

    相当于设置 DeviceFilter.vendorId。

HidCollectionInfo

属性

  • reportIds

    number[]

    属于相应集合及其子集合的报告 ID。

  • 使用量

    数值

    页面定义的用途标识符。

  • usagePage

    数值

    HID 用途页面标识符。

HidConnectInfo

属性

  • connectionId

    数值

    用于在所有其他函数中标识相应连接的不透明 ID。

HidDeviceInfo

属性

  • 收藏集

    HidCollectionInfo[]

    相应设备报告描述符中的顶级集合。

  • deviceId

    数值

    不透明设备 ID。

  • maxFeatureReportSize

    数值

    顶级集合的特征报告大小上限。

  • maxInputReportSize

    数值

    顶级集合的输入报告大小上限。

  • maxOutputReportSize

    数值

    顶级集合的最大输出报告大小。

  • productId

    数值

    商品 ID。

  • productName

    字符串

    Chrome 46 及更高版本

    从设备读取的产品名称（如果有）。

  • reportDescriptor

    ArrayBuffer

    原始设备报告描述符（不适用于 Windows）。

  • serialNumber

    字符串

    Chrome 46 及更高版本

    从设备读取的序列号（如有）。

  • vendorId

    数值

    供应商 ID。

方法

connect()

Promise 
chrome.hid.connect(
  deviceId: number,
  callback?: function,
): Promise<HidConnectInfo>

打开与 HID 设备的连接以进行通信。

参数

返回

  • Promise<HidConnectInfo>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

disconnect()

Promise 
chrome.hid.disconnect(
  connectionId: number,
  callback?: function,
): Promise<void>

断开与设备的连接。在调用此方法后，对设备调用操作是安全的，但不会产生任何效果。

参数

  • connectionId

    数值

    connect 返回的 connectionId。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getDevices()

Promise 
chrome.hid.getDevices(
  options: GetDevicesOptions,
  callback?: function,
): Promise<HidDeviceInfo[]>

枚举已连接的 HID 设备。

参数

返回

  • Promise<HidDeviceInfo[]>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

receive()

chrome.hid.receive(
  connectionId: number,
  callback: function,
): void

接收来自设备的下一个输入报告。

参数

  • connectionId

    数值

    connect 返回的 connectionId。

  • callback

    函数

    callback 参数如下所示： 

    (reportId: number, data: ArrayBuffer) => void

    • reportId

      数值

      报告 ID，如果没有，则为 0。

    • 数据

      ArrayBuffer

      移除报告数据、报告 ID 前缀（如果有）。

receiveFeatureReport()

Promise 
chrome.hid.receiveFeatureReport(
  connectionId: number,
  reportId: number,
  callback?: function,
): Promise<ArrayBuffer>

从设备请求功能报告。

参数

  • connectionId

    数值

    connect 返回的 connectionId。

  • reportId

    数值

    报告 ID，如果没有，则为 0。

  • callback

    函数 可选

    callback 参数如下所示： 

    (data: ArrayBuffer) => void

    • 数据

      ArrayBuffer

      报告数据，包括设备发送的报告 ID 前缀（如果有）。

返回

  • Promise<ArrayBuffer>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

send()

Promise 
chrome.hid.send(
  connectionId: number,
  reportId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

向设备发送输出报告。

注意：请勿在 data 中添加报告 ID 前缀。如有必要，系统会添加该参数。

参数

  • connectionId

    数值

    connect 返回的 connectionId。

  • reportId

    数值

    要使用的报告 ID；如果没有，则为 0。

  • 数据

    ArrayBuffer

    报告数据。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

sendFeatureReport()

Promise 
chrome.hid.sendFeatureReport(
  connectionId: number,
  reportId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

向设备发送功能报告。

注意：请勿在 data 中添加报告 ID 前缀。如有必要，系统会添加该参数。

参数

  • connectionId

    数值

    connect 返回的 connectionId。

  • reportId

    数值

    要使用的报告 ID；如果没有，则为 0。

  • 数据

    ArrayBuffer

    报告数据。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 117 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onDeviceAdded

chrome.hid.onDeviceAdded.addListener(
  callback: function,
)

当设备添加到系统时生成的事件。事件仅广播给有权访问设备的应用和扩展程序。权限可能是在安装时授予的，也可能是在用户接受可选权限时授予的（请参阅 permissions.request）。

参数

onDeviceRemoved

chrome.hid.onDeviceRemoved.addListener(
  callback: function,
)

当设备从系统中移除时生成的事件。如需了解哪些事件会传递，请参阅 onDeviceAdded。

参数

  • callback

    函数

    callback 参数如下所示： 

    (deviceId: number) => void

    • deviceId

      数值