chrome.bluetooth

说明

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

可用性

仅限 ChromeOS

清单

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

"bluetooth"

类型

AdapterState

属性

  • 地址

    字符串

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

  • 可用

    布尔值

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

  • 探索

    布尔值

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

  • name

    字符串

    适配器的人类可读名称。

  • powered

    布尔值

    指示适配器是否已接通电源。

BluetoothFilter

Chrome 67 及更高版本

属性

  • filterType

    FilterType 可选

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

  • 限制

    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

    Transport 可选

    Chrome 76 及更高版本

    蓝牙设备的传输类型。

  • 类型

    DeviceType 可选

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

  • uuids

    string[] 可选

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

  • vendorId

    number 可选

  • vendorIdSource

    VendorIdSource 可选

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

DeviceType

Chrome 识别的常见设备类型。

枚举

"computer"

"phone"

"modem"

"audio"

"carAudio"

"video"

"peripheral"

"joystick"

"gamepad"

"keyboard"

"mouse"

"tablet"

"keyboardMouseCombo"

FilterType

Chrome 67 及更高版本

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

枚举

"all"

"known"

Transport

Chrome 76 及更高版本

蓝牙设备的传输类型。

枚举

"invalid"

"classic"

"le"

"dual"

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[]>

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

参数

  • 过滤条件

    BluetoothFilter 可选

    Chrome 67 及更高版本

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

  • callback

    函数可选

    callback 参数如下所示： 

    (deviceInfos: Device[]) => void

    • deviceInfos

      Device[]

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

返回

  • Promise<Device[]>

    Chrome 91 及更高版本

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

startDiscovery()

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

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

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

参数

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

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

stopDiscovery()

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

停止发现。

参数

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<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