Bluetooth：requestDevice() 方法

语法

requestDevice()
requestDevice(options)

参数

options 可选

一个用于设置选择合适设备的选项的对象。可用选项包括：

filters 可选

一个过滤器对象数组，指示将匹配的设备属性。要匹配一个过滤器对象，设备必须匹配该过滤器中的所有值：即所有指定的 services、name、namePrefix 等。

每个过滤器都包含一个具有以下属性的对象数组

services 可选

一个值数组，指示蓝牙设备必须支持的蓝牙 GATT（通用属性配置文件）服务。每个值可以是 GATT 已分配服务列表 中的有效名称，例如 'battery_service' 或 'blood_pressure'。您也可以传入完整的服务 UUID，例如 '0000180F-0000-1000-8000-00805f9b34fb'，或者 16 位（0x180F）或 32 位短别名。请注意，这些值与可以传递给 BluetoothUUID.getService() 的值相同。

name 可选

一个包含设备精确名称的字符串，用于匹配。

namePrefix 可选

一个包含名称前缀的字符串，用于匹配。所有名称以该字符串开头的设备都将被匹配。

manufacturerData 可选

一个对象数组，用于匹配蓝牙低功耗 (BLE) 广告包中的制造商数据。每个过滤器对象具有以下属性：

companyIdentifier

一个必需的数字，用于标识设备的制造商。公司标识符列在蓝牙规范 已分配号码 的第 7 部分中。例如，要匹配由“Digianswer A/S”制造的设备（十六进制分配号为 0x000C），您应指定 12。

dataPrefix 可选

数据前缀。一个缓冲区，包含用于匹配广告制造商数据开头的值。

mask 可选

这允许您通过屏蔽服务数据 dataPrefix 的某些字节来匹配制造商数据中的字节。

serviceData 可选

一个对象数组，用于匹配蓝牙低功耗 (BLE) 广告包中的服务数据。每个过滤器对象具有以下属性：

service

GATT 服务名称、服务 UUID，或 16 位或 32 位 UUID 形式。这接受的值与 services 数组的元素相同。

dataPrefix 可选

数据前缀。一个缓冲区，包含用于匹配广告服务数据开头的值。

mask 可选

这允许您通过屏蔽服务数据 dataPrefix 的某些字节来匹配服务数据中的字节。

exclusionFilters 可选

一个过滤器对象数组，指示将从匹配中排除的设备特征。数组元素的属性与 filters 的属性相同。

optionalServices 可选

一个可选服务标识符数组。

标识符接受的值与 services 数组的元素相同（GATT 服务名称、服务 UUID，或 16 位或 32 位 UUID 形式）。

optionalManufacturerData 可选

一个可选的整数制造商代码数组。这接受的值与 companyIdentifier 相同。

该数据不用于过滤设备，但符合指定集合的广告仍然会在 advertisementreceived 事件中发送。这很有用，因为它允许代码指定对来自蓝牙设备的数据感兴趣，而不限制用于在权限提示中向用户呈现的设备筛选器。

acceptAllDevices 可选

一个布尔值，指示请求脚本可以接受所有蓝牙设备。默认值为 false。

当设备没有广播足够的信息以进行有效筛选时，此选项非常适用。当 acceptAllDevices 设置为 true 时，您应省略所有 filters 和 exclusionFilters，并且必须设置 optionalServices 才能 *使用* 返回的设备。

在用户为当前源选择了配对设备后，只能访问在 filters.services 的任何元素或 optionalServices 中列出的服务的 UUID。因此，列出所需服务很重要。特别是，仅使用 name 进行筛选时，您必须记住在 optionalServices 中指定所需服务。

返回值

一个 Promise，解析为 BluetoothDevice 对象。

异常

TypeError

如果提供的 options 无效，则抛出。例如，如果 options.filters 存在且 options.acceptAllDevices 为 true，或者 options.filters 不存在且 options.acceptAllDevices 为 false，或者 options.filters 为 []。

NotFoundError DOMException

如果没有与指定选项匹配的蓝牙设备，则抛出。

SecurityError DOMException

如果由于 安全考虑（例如，从不安全来源调用）而在当前上下文中不允许此操作，则抛出。

示例

// Discovery options match any devices advertising:
// - The standard heart rate service.
// - Both 16-bit service IDs 0x1802 and 0x1803.
// - A proprietary 128-bit UUID service c48e6067-5295-48d3-8d5c-0395f61792b1.
// - Devices with name "ExampleName".
// - Devices with name starting with "Prefix".
//
// And enables access to the battery service if devices
// include it, even if devices do not advertise that service.
let options = {
  filters: [
    { services: ["heart_rate"] },
    { services: [0x1802, 0x1803] },
    { services: ["c48e6067-5295-48d3-8d5c-0395f61792b1"] },
    { name: "ExampleName" },
    { namePrefix: "Prefix" },
  ],
  optionalServices: ["battery_service"],
};

navigator.bluetooth
  .requestDevice(options)
  .then((device) => {
    console.log(`Name: ${device.name}`);
    // Do something with the device.
  })
  .catch((error) => console.error(`Something went wrong. ${error}`));

详细示例 位于规范中，以及 developer.chrome.com 上的 通过 JavaScript 与蓝牙设备通信。

规范

浏览器兼容性

另见

• 通过 JavaScript 与蓝牙设备通信，来自 developer.chrome.com。