chrome.usb

说明

使用 chrome.usb API 与连接的 USB 设备进行交互。此 API 支持从应用环境中访问 USB 操作。使用此 API，应用可以充当硬件设备的驱动程序。通过设置 runtime.lastError 并执行函数的常规回调来报告此 API 生成的错误。在这种情况下，回调的常规参数将处于未定义状态。

权限

usb

类型

ConfigDescriptor

属性

  • 活跃

    布尔值

    Chrome 47 及更高版本

    这是有效配置吗？

  • configurationValue

    number

    配置编号。

  • 说明

    字符串（可选）

    配置的说明。

  • extra_data

    数组缓冲区

    与此配置关联的其他描述符数据。

  • 可用的接口。

  • maxPower

    number

    此设备所需的最大功率，以毫安 (mA) 为单位。

  • remoteWakeup

    布尔值

    设备支持远程唤醒。

  • selfPowered

    布尔值

    设备自供电。

ConnectionHandle

属性

  • 句柄

    number

    一个不透明句柄，用于表示与 USB 设备、所有关联的已声明接口和待处理传输的连接。每次打开设备时，系统都会创建一个新句柄。连接句柄与 Device.device 不同。

  • productId

    number

    产品 ID。

  • vendorId

    number

    设备供应商 ID。

ControlTransferInfo

属性

  • 数据

    ArrayBuffer 可选

    要传输的数据（仅输出传输需要）。

  • 方向

    方向

    转账方向（"in" 或 "out"）。

  • 索引

    number

    wIndex 字段，请参见同上。

  • 长度

    编号（选填）

    要接收的最大字节数（仅输入传输需要）。

  • 接收人

    收件人

    转移目标。如果值为 "interface" 或 "endpoint"，则必须声明 index 指定的目标。

  • request

    number

    对于 bRequest 字段，请参阅通用串行总线规范修订版 1.1 § 9.3。

  • requestType

    RequestType

    请求类型。

  • 超时

    编号（选填）

    Chrome 43 及更高版本

    请求超时（以毫秒为单位）。默认值 0 表示无超时。

  • 值

    number

    wValue 字段，请参见同上。

Device

属性

  • 设备

    number

    USB 设备的不透明 ID。在设备被拔下之前，此 ID 会保持不变。

  • manufacturerName

    字符串

    Chrome 46 及更高版本

    从设备读取的 iManufacturer 字符串（如果有）。

  • productId

    number

    产品 ID。

  • productName

    字符串

    Chrome 46 及更高版本

    从设备读取的 iProduct 字符串（如果有）。

  • serialNumber

    字符串

    Chrome 46 及更高版本

    从设备读取的 iSerialNumber 字符串（如果有）。

  • vendorId

    number

    设备供应商 ID。

  • 版本

    number

    Chrome 51 及更高版本

    设备版本（bcdDevice 字段）。

DeviceFilter

属性

  • interfaceClass

    编号（选填）

    USB 接口类，与设备上的任何接口匹配。

  • interfaceProtocol

    编号（选填）

    USB 接口协议，仅在接口子类匹配时选中。

  • interfaceSubclass

    编号（选填）

    USB 接口子类，仅在接口类匹配时才勾选。

  • productId

    编号（选填）

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

  • vendorId

    编号（选填）

    设备供应商 ID。

DevicePromptOptions

属性

  • 过滤条件

    DeviceFilter[] 可选

    过滤呈现给用户的设备列表。如果提供了多个过滤条件，系统会显示与任意过滤条件匹配的设备。

  • 多个

    布尔值（可选）

    允许用户选择多台设备。

Direction

Direction、Recipient、RequestType 和 TransferType 均映射到 USB 规范中的对应名称。

枚举

"in"

"输出"

EndpointDescriptor

属性

  • 地址

    number

    端点地址。

  • 方向

    方向

    转接方向。

  • extra_data

    数组缓冲区

    与此端点关联的额外描述符数据。

  • maximumPacketSize

    number

    数据包大小上限。

  • pollingInterval

    编号（选填）

    轮询间隔（仅限中断和等时）。

  • 同步

    SynchronizationType 可选

    传输同步模式（仅限等时）。

  • 类型

    TransferType

    传输类型。

  • 使用量

    UsageType（选填）

    端点使用提示。

EnumerateDevicesAndRequestAccessOptions

属性

  • interfaceId

    编号（选填）

    要请求访问权限的接口 ID。仅适用于 ChromeOS。对其他平台没有影响。

  • productId

    number

    产品 ID。

  • vendorId

    number

    设备供应商 ID。

EnumerateDevicesOptions

属性

  • 过滤条件

    DeviceFilter[] 可选

    系统将返回与任意指定过滤条件匹配的设备。空的过滤条件列表将返回应用有权使用的所有设备。

  • productId

    编号（选填）

    <ph type="x-smartling-placeholder"></ph> 已弃用

    相当于设置 DeviceFilter.productId。

  • vendorId

    编号（选填）

    <ph type="x-smartling-placeholder"></ph> 已弃用

    相当于设置 DeviceFilter.vendorId。

GenericTransferInfo

属性

  • 数据

    ArrayBuffer 可选

    要传输的数据（仅输出传输需要）。

  • 方向

    方向

    转账方向（"in" 或 "out"）。

  • 端点

    number

    目标端点地址。必须声明包含此端点的接口。

  • 长度

    编号（选填）

    要接收的最大字节数（仅输入传输需要）。

  • 超时

    编号（选填）

    Chrome 43 及更高版本

    请求超时（以毫秒为单位）。默认值 0 表示无超时。

InterfaceDescriptor

属性

  • alternateSetting

    number

    界面备用设置编号（默认为 0）

  • 说明

    字符串（可选）

    接口的说明。

  • endpoints

    EndpointDescriptor[]

    可用的端点。

  • extra_data

    数组缓冲区

    与此接口关联的额外描述符数据。

  • interfaceClass

    number

    USB 接口类。

  • interfaceNumber

    number

    接口编号。

  • interfaceProtocol

    number

    USB 接口协议。

  • interfaceSubclass

    number

    USB 接口子类。

IsochronousTransferInfo

属性

  • packetLength

    number

    此传输中每个数据包的长度。

  • 数据包

    number

    此传输中的数据包总数。

  • transferInfo

    GenericTransferInfo

    传输参数。此参数块中指定的传输长度或数据缓冲区会沿着 packetLength 边界进行拆分，以形成传输的各个数据包。

Recipient

枚举

“device”

"接口"

“端点”

“其他”

RequestType

枚举

“标准”

"class"

"vendor"

"已预留"

SynchronizationType

对于中断模式和等时模式，SynchronizationType 和 UsageType 会映射到 USB 规范中的相应名称。

枚举

“asynchronous”

"自适应"

“同步”

TransferResultInfo

属性

  • 数据

    ArrayBuffer 可选

    输入传输返回的数据。undefined，用于输出传输。

  • resultCode

    编号（选填）

    值 0 表示转移成功。其他值表示失败。

TransferType

枚举

"control"

"中断"

“等时”

"批量"

UsageType

枚举

"数据"

"反馈"

“显式反馈”

"periodic"

“通知”

方法

bulkTransfer()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

在指定设备上执行批量传输。

参数

返回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 及更高版本

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

claimInterface()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

声明 USB 设备上的接口。在将数据传输到某个接口或关联端点之前，必须先声明对该接口的所有权。在任何给定时间，只有一个连接句柄可以声明接口。如果接口已被声明，则此调用将失败。

当不再需要该接口时，应调用 releaseInterface。

参数

  • 与设备的开放连接。

  • interfaceNumber

    number

    要声明的接口。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

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

closeDevice()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
)

关闭连接句柄。在句柄关闭后对其执行操作是安全操作，但会导致不执行任何操作。

参数

返回

  • 承诺<void>

    Chrome 116 及更高版本

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

controlTransfer()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
)

在指定设备上执行控件传输。

控制传输涉及设备、接口或端点。若要将数据转移到某个接口或端点，您需要声明对该接口的所有权。

参数

返回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 及更高版本

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

findDevices()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
)

查找由供应商、产品和（可选）接口 ID 指定的 USB 设备，并在权限允许的情况下打开这些设备以供使用。

如果访问请求被拒绝或无法打开设备，系统将不会创建或返回连接句柄。

调用此方法等同于先调用 getDevices，然后再针对每个设备调用 openDevice。

参数

返回

  • Promise&lt;ConnectionHandle[]&gt;

    Chrome 116 及更高版本

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

getConfiguration()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
)

获取当前所选配置的配置描述符。

参数

返回

  • Promise&lt;ConfigDescriptor&gt;

    Chrome 116 及更高版本

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

getConfigurations()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 47 及更高版本 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

返回完整的设备配置描述符集合。

参数

返回

  • Promise&lt;ConfigDescriptor[]&gt;

    Chrome 116 及更高版本

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

getDevices()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
)

枚举连接的 USB 设备。

参数

  • 要在目标设备上搜索的属性。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (devices: Device[]) => void

返回

  • Promise<设备 []>

    Chrome 116 及更高版本

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

getUserSelectedDevices()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
)

向用户显示设备选择器并返回选定的 Device。如果用户取消，选择器设备将为空。需要用户手势才能显示此对话框。如果没有用户手势，回调将如用户取消操作一样运行。

参数

  • 设备选择器对话框的配置。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (devices: Device[]) => void

返回

  • Promise<设备 []>

    Chrome 116 及更高版本

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

interruptTransfer()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

在指定设备上执行中断传输。

参数

返回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 及更高版本

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

isochronousTransfer()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
)

在特定设备上执行等时传输。

参数

返回

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 及更高版本

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

listInterfaces()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
)

列出 USB 设备上的所有接口。

参数

返回

  • Promise&lt;InterfaceDescriptor[]&gt;

    Chrome 116 及更高版本

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

openDevice()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
)

打开 getDevices 返回的 USB 设备。

参数

返回

  • Promise&lt;ConnectionHandle&gt;

    Chrome 116 及更高版本

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

releaseInterface()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

释放已声明的接口。

参数

  • 与设备的开放连接。

  • interfaceNumber

    number

    要发布的接口。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

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

requestAccess()

<ph type="x-smartling-placeholder"></ph> 承诺 已弃用
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

此函数特定于 Chrome 操作系统，在其他平台上调用会失败。此操作现在作为 openDevice 的一部分隐式执行，并且此函数将在所有平台上返回 true。

向权限代理请求对已由 Chrome 操作系统声明版权的设备的访问权限，但前提是该设备的指定接口未被声明。

参数

  • 设备

    设备

    要请求访问权限的 Device。

  • interfaceId

    number

    请求的特定接口。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 116 及更高版本

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

resetDevice()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
)

正在尝试重置 USB 设备。如果重置失败，指定连接手柄将被关闭，并且 USB 设备会显示为已断开连接然后重新连接。在这种情况下，必须再次调用 getDevices 或 findDevices 才能获取设备。

参数

  • 要重置的连接句柄。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 116 及更高版本

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

setConfiguration()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
)

选择设备配置。

此函数通过选择设备的其中一个可用配置来有效地重置设备。只有大于 0 的配置值才有效，不过，某些有错误的设备具有可以正常使用的配置值 0，因此系统允许使用此值。

参数

  • 与设备的开放连接。

  • configurationValue

    number

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

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

setInterfaceAlternateSetting()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
)

在之前声明的界面上选择备用设置。

参数

  • 已声明拥有此接口的设备的开放连接。

  • interfaceNumber

    number

    要配置的接口。

  • alternateSetting

    number

    要配置的备用设置。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

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

事件

onDeviceAdded

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

将设备添加到系统时生成的事件。系统仅会向有权访问该设备的应用和扩展程序广播事件。权限可能是在安装时、用户接受可选权限时（请参阅 permissions.request）或通过 getUserSelectedDevices 授予的。

参数

  • callback

    函数

    callback 参数如下所示： 

    (device: Device) => void

onDeviceRemoved

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (device: Device) => void