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 来源）可选

    设备的设备 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()

prometido 
chrome.bluetooth.getAdapterState(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (adapterInfo: AdapterState) => void

    • adapterInfo

      AdapterState

      包含适配器信息的对象。

返回

  • Promise<AdapterState>

    Chrome 91 及更高版本

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

getDevice()

prometido 
chrome.bluetooth.getDevice(
  deviceAddress: string,
  callback?: function,
)

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

参数

  • deviceAddress

    字符串

    要获取的设备的地址。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (deviceInfo: Device) => void

    • deviceInfo

      设备

      包含设备信息的对象。

返回

  • Promise<Device>

    Chrome 91 及更高版本

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

getDevices()

prometido 
chrome.bluetooth.getDevices(
  filter?: BluetoothFilter,
  callback?: function,
)

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

参数

  • filter

    BluetoothFilter（可选）

    Chrome 67 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (deviceInfos: Device[]) => void

    • deviceInfos

      Device[]

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

返回

  • Promise<Device[]>

    Chrome 91 及更高版本

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

startDiscovery()

prometido 
chrome.bluetooth.startDiscovery(
  callback?: function,
)

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

如果此应用已调用 startDiscovery，则发现会失败。发现功能可能需要大量资源：应尽快调用 stopDiscovery。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 91 及更高版本

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

stopDiscovery()

prometido 
chrome.bluetooth.stopDiscovery(
  callback?: function,
)

停止发现。

参数

  • 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