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。