说明
使用 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
请求类型。
-
超时
编号(选填)
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
编号(选填)
轮询间隔(仅限中断和等时)。
-
同步
传输同步模式(仅限等时)。
-
类型
传输类型。
-
使用量
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
可用的端点。
-
extra_data
数组缓冲区
与此接口关联的额外描述符数据。
-
interfaceClass
number
USB 接口类。
-
interfaceNumber
number
接口编号。
-
interfaceProtocol
number
USB 接口协议。
-
interfaceSubclass
number
USB 接口子类。
IsochronousTransferInfo
属性
-
packetLength
number
此传输中每个数据包的长度。
-
数据包
number
此传输中的数据包总数。
-
transferInfo
传输参数。此参数块中指定的传输长度或数据缓冲区会沿着
packetLength
边界进行拆分,以形成传输的各个数据包。
Recipient
枚举
“device”
"接口"
“端点”
“其他”
RequestType
枚举
“标准”
"class"
"vendor"
"已预留"
SynchronizationType
对于中断模式和等时模式,SynchronizationType 和 UsageType 会映射到 USB 规范中的相应名称。
枚举
“asynchronous”
"自适应"
“同步”
TransferResultInfo
属性
-
数据
ArrayBuffer 可选
输入传输返回的数据。
undefined
,用于输出传输。 -
resultCode
编号(选填)
值
0
表示转移成功。其他值表示失败。
TransferType
枚举
"control"
"中断"
“等时”
"批量"
UsageType
枚举
"数据"
"反馈"
“显式反馈”
"periodic"
“通知”
方法
bulkTransfer()
chrome.usb.bulkTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
在指定设备上执行批量传输。
参数
-
与设备的开放连接。
-
transferInfo
传输参数。
-
callback
函数(可选)
callback
参数如下所示:(info: TransferResultInfo) => void
返回
-
Promise<TransferResultInfo>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
claimInterface()
chrome.usb.claimInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
声明 USB 设备上的接口。在将数据传输到某个接口或关联端点之前,必须先声明对该接口的所有权。在任何给定时间,只有一个连接句柄可以声明接口。如果接口已被声明,则此调用将失败。
当不再需要该接口时,应调用 releaseInterface
。
参数
-
与设备的开放连接。
-
interfaceNumber
number
要声明的接口。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
closeDevice()
chrome.usb.closeDevice(
handle: ConnectionHandle,
callback?: function,
)
关闭连接句柄。在句柄关闭后对其执行操作是安全操作,但会导致不执行任何操作。
参数
-
要关闭的
ConnectionHandle
。 -
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
controlTransfer()
chrome.usb.controlTransfer(
handle: ConnectionHandle,
transferInfo: ControlTransferInfo,
callback?: function,
)
在指定设备上执行控件传输。
控制传输涉及设备、接口或端点。若要将数据转移到某个接口或端点,您需要声明对该接口的所有权。
参数
-
与设备的开放连接。
-
transferInfo
-
callback
函数(可选)
callback
参数如下所示:(info: TransferResultInfo) => void
返回
-
Promise<TransferResultInfo>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
findDevices()
chrome.usb.findDevices(
options: EnumerateDevicesAndRequestAccessOptions,
callback?: function,
)
查找由供应商、产品和(可选)接口 ID 指定的 USB 设备,并在权限允许的情况下打开这些设备以供使用。
如果访问请求被拒绝或无法打开设备,系统将不会创建或返回连接句柄。
调用此方法等同于先调用 getDevices
,然后再针对每个设备调用 openDevice
。
参数
-
要在目标设备上搜索的属性。
-
callback
函数(可选)
callback
参数如下所示:(handles: ConnectionHandle[]) => void
-
标识名
-
返回
-
Promise<ConnectionHandle[]>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getConfiguration()
chrome.usb.getConfiguration(
handle: ConnectionHandle,
callback?: function,
)
获取当前所选配置的配置描述符。
参数
-
与设备的开放连接。
-
callback
函数(可选)
callback
参数如下所示:(config: ConfigDescriptor) => void
-
config
-
返回
-
Promise<ConfigDescriptor>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getConfigurations()
chrome.usb.getConfigurations(
device: Device,
callback?: function,
)
返回完整的设备配置描述符集合。
参数
-
设备
要从中提取描述符的
Device
。 -
callback
函数(可选)
callback
参数如下所示:(configs: ConfigDescriptor[]) => void
-
configs
-
返回
-
Promise<ConfigDescriptor[]>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getDevices()
chrome.usb.getDevices(
options: EnumerateDevicesOptions,
callback?: function,
)
枚举连接的 USB 设备。
参数
getUserSelectedDevices()
chrome.usb.getUserSelectedDevices(
options: DevicePromptOptions,
callback?: function,
)
向用户显示设备选择器并返回选定的 Device
。如果用户取消,选择器设备将为空。需要用户手势才能显示此对话框。如果没有用户手势,回调将如用户取消操作一样运行。
参数
interruptTransfer()
chrome.usb.interruptTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
在指定设备上执行中断传输。
参数
-
与设备的开放连接。
-
transferInfo
传输参数。
-
callback
函数(可选)
callback
参数如下所示:(info: TransferResultInfo) => void
返回
-
Promise<TransferResultInfo>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
isochronousTransfer()
chrome.usb.isochronousTransfer(
handle: ConnectionHandle,
transferInfo: IsochronousTransferInfo,
callback?: function,
)
在特定设备上执行等时传输。
参数
-
与设备的开放连接。
-
transferInfo
-
callback
函数(可选)
callback
参数如下所示:(info: TransferResultInfo) => void
返回
-
Promise<TransferResultInfo>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
listInterfaces()
chrome.usb.listInterfaces(
handle: ConnectionHandle,
callback?: function,
)
列出 USB 设备上的所有接口。
参数
-
与设备的开放连接。
-
callback
函数(可选)
callback
参数如下所示:(descriptors: InterfaceDescriptor[]) => void
-
描述符
-
返回
-
Promise<InterfaceDescriptor[]>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
openDevice()
chrome.usb.openDevice(
device: Device,
callback?: function,
)
打开 getDevices
返回的 USB 设备。
参数
-
设备
要打开的
Device
。 -
callback
函数(可选)
callback
参数如下所示:(handle: ConnectionHandle) => void
返回
-
Promise<ConnectionHandle>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
releaseInterface()
chrome.usb.releaseInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
释放已声明的接口。
参数
-
与设备的开放连接。
-
interfaceNumber
number
要发布的接口。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
requestAccess()
chrome.usb.requestAccess(
device: Device,
interfaceId: number,
callback?: function,
)
此函数特定于 Chrome 操作系统,在其他平台上调用会失败。此操作现在作为 openDevice
的一部分隐式执行,并且此函数将在所有平台上返回 true
。
向权限代理请求对已由 Chrome 操作系统声明版权的设备的访问权限,但前提是该设备的指定接口未被声明。
参数
-
设备
要请求访问权限的
Device
。 -
interfaceId
number
请求的特定接口。
-
callback
函数(可选)
callback
参数如下所示:(success: boolean) => void
-
成功
布尔值
-
返回
-
Promise<boolean>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
resetDevice()
chrome.usb.resetDevice(
handle: ConnectionHandle,
callback?: function,
)
正在尝试重置 USB 设备。如果重置失败,指定连接手柄将被关闭,并且 USB 设备会显示为已断开连接然后重新连接。在这种情况下,必须再次调用 getDevices
或 findDevices
才能获取设备。
参数
-
要重置的连接句柄。
-
callback
函数(可选)
callback
参数如下所示:(success: boolean) => void
-
成功
布尔值
-
返回
-
Promise<boolean>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setConfiguration()
chrome.usb.setConfiguration(
handle: ConnectionHandle,
configurationValue: number,
callback?: function,
)
选择设备配置。
此函数通过选择设备的其中一个可用配置来有效地重置设备。只有大于 0
的配置值才有效,不过,某些有错误的设备具有可以正常使用的配置值 0
,因此系统允许使用此值。
参数
-
与设备的开放连接。
-
configurationValue
number
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setInterfaceAlternateSetting()
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
授予的。
onDeviceRemoved
chrome.usb.onDeviceRemoved.addListener(
callback: function,
)
从系统中移除设备时生成的事件。如需了解系统会传送哪些事件,请参阅 onDeviceAdded
。