说明
使用 chrome.usb
API 与已连接的 USB 设备交互。此 API 支持从应用上下文访问 USB 操作。使用此 API,应用可用作硬件设备的驱动程序。系统会通过设置 runtime.lastError
并执行函数的常规回调来报告此 API 生成的错误。在这种情况下,回调的常规参数将未定义。
权限
usb
类型
ConfigDescriptor
属性
-
活跃
boolean
Chrome 47 及更高版本这是活跃配置吗?
-
configurationValue
number
配置编号。
-
说明
字符串(可选)
配置的说明。
-
extra_data
ArrayBuffer
与此配置相关联的额外描述符数据。
-
接口
可用的接口。
-
maxPower
number
此设备所需的最大功率,以毫安 (mA) 为单位。
-
remoteWakeup
boolean
设备支持远程唤醒。
-
selfPowered
boolean
该设备需要自供电。
ConnectionHandle
属性
-
标识名
number
一个不透明的句柄,用于表示与 USB 设备、所有关联的已声明接口和待处理的传输的连接。每次打开设备时,系统都会创建一个新句柄。连接句柄与
Device.device
不同。 -
productId
number
产品 ID。
-
vendorId
number
设备供应商 ID。
ControlTransferInfo
属性
-
data
ArrayBuffer 可选
要传输的数据(仅输出传输需要)。
-
direction
传输方向(
"in"
或"out"
)。 -
索引
number
wIndex
字段,请参阅 Ibid。 -
length
数字可选
要接收的字节数上限(仅输入传输需要)。
-
接收人
传输目标。如果为
"interface"
或"endpoint"
,则必须声明index
提供的目标。 -
request
number
bRequest
字段,请参阅通用串行总线规范修订版 1.1 § 9.3。 -
requestType
请求类型。
-
超时
数字可选
Chrome 43 及更高版本请求超时(以毫秒为单位)。默认值
0
表示没有超时。 -
值
number
wValue
字段,请参阅 Ibid。
Device
属性
-
设备
number
USB 设备的不透明 ID。在将设备拔出之前,电源线会保持不变。
-
manufacturerName
string
Chrome 46 及更高版本从设备读取的 iManufacturer 字符串(如果有)。
-
productId
number
产品 ID。
-
productName
string
Chrome 46 及更高版本从设备读取的 iProduct 字符串(如果有)。
-
serialNumber
string
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 规范中的同名项。
枚举
EndpointDescriptor
属性
-
地址
number
端点地址。
-
direction
传输方向。
-
extra_data
ArrayBuffer
与此端点相关联的额外描述符数据。
-
maximumPacketSize
number
数据包大小上限。
-
pollingInterval
数字可选
轮询间隔(仅限中断和等时)。
-
同步
传输同步模式(仅限等时)。
-
类型
传输类型。
-
使用量
UsageType(可选)
端点使用提示。
EnumerateDevicesAndRequestAccessOptions
属性
-
interfaceId
数字可选
要请求访问的接口 ID。仅适用于 ChromeOS。对其他平台没有任何影响。
-
productId
number
产品 ID。
-
vendorId
number
设备供应商 ID。
EnumerateDevicesOptions
属性
-
过滤条件
DeviceFilter[] 可选
系统将返回与任意指定过滤条件相匹配的设备。如果过滤器列表为空,系统将返回应用有权使用的所有设备。
-
productId
数字可选
已废弃相当于设置
DeviceFilter.productId
。 -
vendorId
数字可选
已废弃相当于设置
DeviceFilter.vendorId
。
GenericTransferInfo
属性
-
data
ArrayBuffer 可选
要传输的数据(仅输出传输需要)。
-
direction
传输方向(
"in"
或"out"
)。 -
端点
number
目标端点地址。必须声明包含此端点的接口。
-
length
数字可选
要接收的字节数上限(仅输入传输需要)。
-
超时
数字可选
Chrome 43 及更高版本请求超时(以毫秒为单位)。默认值
0
表示没有超时。
InterfaceDescriptor
属性
-
alternateSetting
number
接口备用设置编号(默认为
0
) -
说明
字符串(可选)
接口的说明。
-
endpoints
可用的端点。
-
extra_data
ArrayBuffer
与此接口相关联的额外描述符数据。
-
interfaceClass
number
USB 接口类。
-
interfaceNumber
number
接口编号。
-
interfaceProtocol
number
USB 接口协议。
-
interfaceSubclass
number
USB 接口子类。
IsochronousTransferInfo
属性
-
packetLength
number
此传输作业中每个数据包的长度。
-
数据包
number
此传输作业中的数据包总数。
-
transferInfo
传输参数。此参数块中指定的传输长度或数据缓冲区会沿
packetLength
边界拆分,以形成传输的各个数据包。
Recipient
枚举
"interface"
"endpoint"
RequestType
枚举
"class"
"vendor"
SynchronizationType
对于中断和等时模式,SynchronizationType 和 UsageType 映射到其在 USB 规范中的同名。
枚举
"adaptive"
TransferResultInfo
属性
-
data
ArrayBuffer 可选
输入传输返回的数据。
undefined
,用于输出传输。 -
resultCode
数字可选
值
0
表示转移成功。其他值表示失败。
TransferType
枚举
"control"
"bulk"
(批量)
UsageType
枚举
"feedback"
"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
返回
-
Promise<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
closeDevice()
chrome.usb.closeDevice(
handle: ConnectionHandle,
callback?: function,
)
关闭连接句柄。在句柄关闭后对其进行调用操作是一项安全操作,但不会执行任何操作。
参数
-
标识名
要关闭的
ConnectionHandle
。 -
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<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
-
descriptors
-
返回
-
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
返回
-
Promise<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
requestAccess()
chrome.usb.requestAccess(
device: Device,
interfaceId: number,
callback?: function,
)
此函数是 ChromeOS 专用的函数,在其他平台上调用该函数会失败。现在,此操作作为 openDevice
的一部分隐式执行,并且此函数将在所有平台上返回 true
。
如果未声明对设备上的指定接口的所有权,则向 Chrome 操作系统声明了所有权的设备请求权限代理的访问权限。
参数
-
设备
要请求访问权限的
Device
。 -
interfaceId
number
请求的特定接口。
-
callback
函数(可选)
callback
参数如下所示:(success: boolean) => void
-
成功
boolean
-
返回
-
Promise<boolean>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
resetDevice()
chrome.usb.resetDevice(
handle: ConnectionHandle,
callback?: function,
)
尝试重置 USB 设备。如果重置失败,给定的连接句柄会被关闭,而 USB 设备会显示为已断开连接,然后重新连接。在这种情况下,必须再次调用 getDevices
或 findDevices
以获取设备。
参数
-
标识名
要重置的连接句柄。
-
callback
函数(可选)
callback
参数如下所示:(success: boolean) => void
-
成功
boolean
-
返回
-
Promise<boolean>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setConfiguration()
chrome.usb.setConfiguration(
handle: ConnectionHandle,
configurationValue: number,
callback?: function,
)
选择设备配置。
该功能通过选择设备的其中一种可用配置来有效地重置设备。只有大于 0
的配置值才有效,不过某些有 bug 的设备的 0
配置可正常运行,因此系统允许使用此值。
参数
-
标识名
已连接到设备。
-
configurationValue
number
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<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
返回
-
Promise<void>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onDeviceAdded
chrome.usb.onDeviceAdded.addListener(
callback: function,
)
将设备添加到系统时生成的事件。系统只会向有权访问设备的应用和扩展程序广播事件。此权限可能是在用户安装时授予,或是在用户接受可选权限(请参阅 permissions.request
)时授予,也可通过 getUserSelectedDevices
授予。
onDeviceRemoved
chrome.usb.onDeviceRemoved.addListener(
callback: function,
)
从系统中移除设备时生成的事件。如需了解传送哪些事件,请参阅 onDeviceAdded
。