chrome.bluetooth

说明

使用 chrome.bluetooth API 连接到蓝牙设备。所有函数都会通过 chrome.runtime.lastError 报告失败情况。

清单

如需使用此 API，必须在清单中声明以下键。

"bluetooth"

类型

AdapterState

属性

  • 地址

    字符串

    适配器的地址，格式为“XX:XX:XX:XX:XX:XX”。

  • 可用

    布尔值

    指示适配器是否可用（即是否已启用）。

  • 发现

    布尔值

    指示适配器当前是否正在进行发现。

  • name

    字符串

    适配器的简明易懂的名称。

  • 有源

    布尔值

    指示适配器是否已通电。

BluetoothFilter

Chrome 67 及更高版本

属性

  • filterType

    FilterType 可选

    要应用于设备列表的过滤条件类型。默认值为全部。

  • 限制

    number 可选

    要返回的蓝牙设备数量上限。如果未指定，则默认值为 0（无限制）。

Device

属性

  • 地址

    字符串

    设备的地址，格式为“XX:XX:XX:XX:XX:XX”。

  • batteryPercentage

    number 可选

    Chrome 77 及更高版本

    设备的剩余电量。

  • 可连接

    布尔值（可选）

    Chrome 48 及更高版本

    指示设备是否可连接。

  • 已连接

    布尔值（可选）

    指示设备当前是否已连接到系统。

  • 中转航班

    布尔值（可选）

    Chrome 48 及更高版本

    指示设备当前是否正在连接到系统。

  • deviceClass

    number 可选

    设备的类别，由 http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband 定义的位字段。

  • deviceId

    number 可选

  • inquiryRssi

    number 可选

    Chrome 44 及更高版本

    接收到的信号强度（以 dBm 为单位）。此字段仅在发现期间可用且有效。在发现之外，其值未指定。

  • inquiryTxPower

    number 可选

    Chrome 44 及更高版本

    传输功率电平。此字段仅适用于在 AD 中包含此字段的 LE 设备。它仅在发现期间可用且有效。

  • name

    字符串（选填）

    设备的简明易懂的名称。

  • 已配对

    布尔值（可选）

    指示设备是否已与系统配对。

  • productId

    number 可选

  • transport

    交通（可选）

    Chrome 76 及更高版本

    蓝牙设备的传输类型。

  • 类型

    DeviceType（可选）

    设备类型（如果 Chrome 可以识别）。此值从 deviceClass 字段中获取，仅表示可能设备类型中的一小部分。如有疑问，您应直接使用 deviceClass 字段。

  • uuids

    string[] 可选

    设备所宣传的协议、配置文件和服务对应的 UUID。对于经典蓝牙设备，此列表是从 EIR 数据和 SDP 表中获取的。对于低能耗设备，此列表是从 AD 和 GATT 主服务中获取的。对于双模式设备，此信息可能来自两者。

  • vendorId

    number 可选

  • vendorIdSource

    VendorIdSource 可选

    设备的设备 ID 记录（如有）。

DeviceType

Chrome 识别的常见设备类型。

枚举

“电脑”

“电话”

“调制解调器”

“音频”

"carAudio"

“视频”

“外围设备”

“操纵杆”

“gamepad”

“键盘”

“mouse”

“平板电脑”

"keyboardMouseCombo"

FilterType

Chrome 67 及更高版本

用于过滤蓝牙设备的类型。

枚举

“全部”

“已知”

Transport

Chrome 76 及更高版本

蓝牙设备的传输类型。

枚举

“无效”

“经典”

“le”

“双重”

VendorIdSource

供应商 ID 的分配机构。

枚举

"bluetooth"

“usb”

方法

getAdapterState()

Promise 
chrome.bluetooth.getAdapterState(
  callback?: function,
): Promise<AdapterState>

获取有关蓝牙适配器的信息。

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (adapterInfo: AdapterState) => void

    • adapterInfo

      AdapterState

      包含适配器信息的对象。

返回

  • Promise<AdapterState>

    Chrome 91 及更高版本

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

getDevice()

Promise 
chrome.bluetooth.getDevice(
  deviceAddress: string,
  callback?: function,
): Promise<Device>

获取有关系统已知的蓝牙设备的信息。

参数

  • deviceAddress

    字符串

    要获取的设备的地址。

  • callback

    函数 可选

    callback 参数如下所示： 

    (deviceInfo: Device) => void

    • deviceInfo

      设备

      包含设备信息的对象。

返回

  • Promise<Device>

    Chrome 91 及更高版本

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

getDevices()

Promise 
chrome.bluetooth.getDevices(
  filter?: BluetoothFilter,
  callback?: function,
): Promise<Device[]>

获取系统已知的蓝牙设备列表，包括已配对的设备和最近发现的设备。

参数

  • filter

    BluetoothFilter 可选

    Chrome 67 及更高版本

    用于过滤返回的蓝牙设备列表的某些条件。如果未设置过滤条件或将其设置为 {}，则返回的设备列表将包含所有蓝牙设备。目前，此功能仅在 ChromeOS 中受支持，对于其他平台，系统会返回完整列表。

  • callback

    函数 可选

    callback 参数如下所示： 

    (deviceInfos: Device[]) => void

    • deviceInfos

      设备[]

      包含设备信息的对象数组。

返回

  • Promise<Device[]>

    Chrome 91 及更高版本

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

startDiscovery()

Promise 
chrome.bluetooth.startDiscovery(
  callback?: function,
): Promise<void>

开始发现。新发现的设备将通过 onDeviceAdded 事件返回。必须使用 getDevices 获取适配器已知的先前发现的设备，并且只有在这些设备的相关信息发生变化时，才会使用 onDeviceChanged 事件进行更新。

如果此应用已调用 startDiscovery，则发现将无法启动。发现功能可能会消耗大量资源：应尽快调用 stopDiscovery。

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 91 及更高版本

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

stopDiscovery()

Promise 
chrome.bluetooth.stopDiscovery(
  callback?: function,
): Promise<void>

停止发现。

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 91 及更高版本

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

事件

onAdapterStateChanged

chrome.bluetooth.onAdapterStateChanged.addListener(
  callback: function,
)

当蓝牙适配器的状态发生变化时触发。

参数

onDeviceAdded

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

当有关于新蓝牙设备的信息可用时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (device: Device) => void

onDeviceChanged

chrome.bluetooth.onDeviceChanged.addListener(
  callback: function,
)

在已知蓝牙设备的相关信息发生更改时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (device: Device) => void

onDeviceRemoved

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

在以下情况下触发：之前发现的蓝牙设备超出范围的时间足够长，以至于被视为再次不可用；配对的设备被移除。

参数

  • callback

    函数

    callback 参数如下所示： 

    (device: Device) => void