蓝牙：requestDevice() 方法

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

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

dataPrefix 可选

数据前缀。一个包含要匹配的值的缓冲区，这些值与广告制造商数据的开头处的值匹配。

mask 可选

这使您可以通过屏蔽服务数据的 dataPrefix 中的一些字节来匹配制造商数据中的字节。

serviceData 可选

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

service

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

dataPrefix 可选

数据前缀。一个包含要匹配的值的缓冲区，这些值与广告服务数据的开头处的值匹配。

mask 可选

这使您可以通过屏蔽服务数据的 dataPrefix 中的一些字节来匹配服务数据中的字节。

exclusionFilters 可选

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

optionalServices 可选

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

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

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 与蓝牙设备通信” 中有详细示例。

• developer.chrome.com 上的“通过 JavaScript 与蓝牙设备通信”。