Bluetooth: phương thức requestDevice()

Cú pháp

requestDevice()
requestDevice(options)

Tham số

options Optional

Một đối tượng thiết lập các tùy chọn để chọn một thiết bị phù hợp. Các tùy chọn hiện có gồm:

filters Optional

Một mảng các đối tượng bộ lọc chỉ ra các thuộc tính của thiết bị sẽ được so khớp. Để khớp với một đối tượng bộ lọc, thiết bị phải khớp với tất cả các giá trị trong bộ lọc: mọi services, name, namePrefix đã chỉ định, v.v.

Mỗi bộ lọc gồm một đối tượng có các thuộc tính sau:

services Optional

Một mảng các giá trị cho biết các dịch vụ Bluetooth GATT (Generic Attribute Profile) mà một thiết bị Bluetooth phải hỗ trợ. Mỗi giá trị có thể là một tên hợp lệ trong danh sách dịch vụ GATT được gán, chẳng hạn như 'battery_service' hoặc 'blood_pressure'. Bạn cũng có thể truyền một UUID dịch vụ đầy đủ như '0000180F-0000-1000-8000-00805f9b34fb' hoặc bí danh ngắn 16-bit (0x180F) hay 32-bit. Lưu ý rằng đây cũng là các giá trị có thể truyền cho BluetoothUUID.getService().

name Optional

Một chuỗi chứa chính xác tên của thiết bị cần so khớp.

namePrefix Optional

Một chuỗi chứa tiền tố tên cần so khớp. Tất cả các thiết bị có tên bắt đầu bằng chuỗi này sẽ được khớp.

manufacturerData Optional

Một mảng các đối tượng dùng để so khớp với dữ liệu nhà sản xuất trong các gói quảng bá Bluetooth Low Energy (BLE). Mỗi đối tượng bộ lọc có các thuộc tính sau:

companyIdentifier

Một số bắt buộc để nhận diện nhà sản xuất của thiết bị. Các mã nhận diện công ty được liệt kê trong Assigned numbers của đặc tả Bluetooth, Mục 7. Ví dụ: để so khớp với thiết bị do "Digianswer A/S" sản xuất, có mã hexa được gán là 0x000C, bạn sẽ chỉ định 12.

dataPrefix Optional

Tiền tố dữ liệu. Một bộ đệm chứa các giá trị để so khớp với các giá trị ở đầu dữ liệu quảng bá của nhà sản xuất.

mask Optional

Cho phép bạn so khớp với các byte trong dữ liệu nhà sản xuất bằng cách áp dụng mặt nạ lên một số byte của dữ liệu dịch vụ dataPrefix.

serviceData Optional

Một mảng các đối tượng dùng để so khớp với dữ liệu dịch vụ trong các gói quảng bá Bluetooth Low Energy (BLE). Mỗi đối tượng bộ lọc có các thuộc tính sau:

service

Tên dịch vụ GATT, UUID dịch vụ, hoặc dạng UUID 16-bit hay 32-bit. Thuộc tính này nhận cùng các giá trị như các phần tử của mảng services.

dataPrefix Optional

Tiền tố dữ liệu. Một bộ đệm chứa các giá trị để so khớp với các giá trị ở đầu dữ liệu quảng bá của dịch vụ.

mask Optional

Cho phép bạn so khớp với các byte trong dữ liệu dịch vụ bằng cách áp dụng mặt nạ lên một số byte của dữ liệu dịch vụ dataPrefix.

exclusionFilters Optional

Một mảng các đối tượng bộ lọc chỉ ra các đặc tính của thiết bị sẽ bị loại khỏi việc so khớp. Các thuộc tính của phần tử trong mảng giống với filters.

optionalServices Optional

Một mảng các mã định danh dịch vụ tùy chọn.

Các mã định danh nhận cùng các giá trị như các phần tử của mảng services (tên dịch vụ GATT, UUID dịch vụ, hoặc dạng UUID ngắn 16-bit hay 32-bit).

optionalManufacturerData Optional

Một mảng tùy chọn các mã số nguyên của nhà sản xuất. Giá trị này nhận cùng các giá trị như companyIdentifier.

Dữ liệu này không được dùng để lọc thiết bị, nhưng các quảng bá khớp với tập đã chỉ định vẫn sẽ được chuyển tới trong các sự kiện advertisementreceived. Điều này hữu ích vì nó cho phép mã chỉ định mối quan tâm đến dữ liệu nhận từ các thiết bị Bluetooth mà không ràng buộc bộ lọc kiểm soát những thiết bị nào được hiển thị cho người dùng trong lời nhắc cấp quyền.

acceptAllDevices Optional

Một giá trị boolean cho biết script yêu cầu có thể chấp nhận mọi thiết bị Bluetooth. Giá trị mặc định là false.

Tùy chọn này phù hợp khi thiết bị không quảng bá đủ thông tin để việc lọc trở nên hữu ích. Khi acceptAllDevices được đặt thành true, bạn nên bỏ qua toàn bộ filters và exclusionFilters, đồng thời phải đặt optionalServices để có thể sử dụng thiết bị được trả về.

Sau khi người dùng chọn một thiết bị để ghép đôi trong origin hiện tại, thiết bị đó chỉ được phép truy cập các dịch vụ có UUID đã được liệt kê trong danh sách dịch vụ của bất kỳ phần tử nào trong filters.services hoặc trong optionalServices. Vì vậy, việc liệt kê các dịch vụ cần thiết là rất quan trọng. Đặc biệt, khi chỉ lọc bằng name, bạn phải nhớ chỉ định thêm các dịch vụ mong muốn trong optionalServices.

Giá trị trả về

Một Promise tới một đối tượng BluetoothDevice.

Ngoại lệ

TypeError

Được ném ra nếu options được cung cấp là không hợp lệ. Ví dụ: nếu options.filters hiện diện và options.acceptAllDevices là true, options.filters không hiện diện và options.acceptAllDevices là false, hoặc options.filters là [].

NotFoundError DOMException

Được ném ra nếu không có thiết bị Bluetooth nào khớp với các tùy chọn được chỉ định.

SecurityError DOMException

Được ném ra nếu thao tác này không được phép trong ngữ cảnh hiện tại do các cân nhắc về bảo mật, chẳng hạn như khi được gọi từ một origin không bảo mật.

Ví dụ

// 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}`));

Ví dụ chi tiết có trong đặc tả và cũng có trong Communicating with Bluetooth devices over JavaScript trên developer.chrome.com.

Thông số kỹ thuật

Tương thích trình duyệt

Xem thêm

• Communicating with Bluetooth devices over JavaScript trên developer.chrome.com.