useBluetooth

反应式 网络蓝牙 API。提供与蓝牙低功耗外设连接和交互的能力。

¥Reactive Web Bluetooth API. Provides the ability to connect and interact with Bluetooth Low Energy peripherals.

Web 蓝牙 API 允许网站使用通用属性配置文件 (GATT) 通过蓝牙 4 无线标准发现设备并与其通信。

¥The Web Bluetooth API lets websites discover and communicate with devices over the Bluetooth 4 wireless standard using the Generic Attribute Profile (GATT).

注意目前它已在 Android M、Chrome OS、Mac 和 Windows 10 中部分实现。有关浏览器兼容性的完整概述，请参阅 Web 蓝牙 API 浏览器兼容性

¥N.B. It is currently partially implemented in Android M, Chrome OS, Mac, and Windows 10. For a full overview of browser compatibility please see Web Bluetooth API Browser Compatibility

注意对于网络蓝牙 API 规范，有许多注意事项需要注意。请参阅 网络蓝牙 W3C 报告草案，了解有关设备检测和连接的众多注意事项。

¥N.B. There are a number of caveats to be aware of with the web bluetooth API specification. Please refer to the Web Bluetooth W3C Draft Report for numerous caveats around device detection and connection.

注意此 API 在 Web Workers 中不可用（不通过 WorkerNavigator 公开）。

¥N.B. This API is not available in Web Workers (not exposed via WorkerNavigator).

示例

source

Your browser does not support the Bluetooth Web API

Not Connected

使用默认值

¥Usage Default

import { useBluetooth } from '@vueuse/core'

const {
  isSupported,
  isConnected,
  device,
  requestDevice,
  server,
} = useBluetooth({
  acceptAllDevices: true,
})

<template>
  <button @click="requestDevice()">
    Request Bluetooth Device
  </button>
</template>

当设备配对并连接后，你就可以根据需要使用服务器对象。

¥When the device has paired and is connected, you can then work with the server object as you wish.

使用电池电量示例

¥Usage Battery Level Example

此示例演示了如何使用 Web 蓝牙 API 来读取电池电量，并从附近的蓝牙设备通过蓝牙低功耗广告电池信息获取更改通知。

¥This sample illustrates the use of the Web Bluetooth API to read battery level and be notified of changes from a nearby Bluetooth Device advertising Battery information with Bluetooth Low Energy.

在这里，我们使用 characteristicvaluechanged 事件监听器来处理读取电池电量特性值。该事件监听器也可以选择处理即将到来的通知。

¥Here, we use the characteristicvaluechanged event listener to handle reading battery level characteristic value. This event listener will optionally handle upcoming notifications as well.

TypeScript

import { pausableWatch, useBluetooth } from '@vueuse/core'

const {
  isSupported,
  isConnected,
  device,
  requestDevice,
  server,
} = useBluetooth({
  acceptAllDevices: true,
  optionalServices: [
    'battery_service',
  ],
})

const batteryPercent = ref<undefined | number>()

const isGettingBatteryLevels = ref(false)

async function getBatteryLevels() {
  isGettingBatteryLevels.value = true

  // Get the battery service:
  const batteryService = await server.getPrimaryService('battery_service')

  // Get the current battery level
  const batteryLevelCharacteristic = await batteryService.getCharacteristic(
    'battery_level',
  )

  // Listen to when characteristic value changes on `characteristicvaluechanged` event:
  batteryLevelCharacteristic.addEventListener('characteristicvaluechanged', (event) => {
    batteryPercent.value = event.target.value.getUint8(0)
  })

  // Convert received buffer to number:
  const batteryLevel = await batteryLevelCharacteristic.readValue()

  batteryPercent.value = await batteryLevel.getUint8(0)
}

const { stop } = pausableWatch(isConnected, (newIsConnected) => {
  if (!newIsConnected || !server.value || isGettingBatteryLevels.value)
    return
  // Attempt to get the battery levels of the device:
  getBatteryLevels()
  // We only want to run this on the initial connection, as we will use an event listener to handle updates:
  stop()
})

import { pausableWatch, useBluetooth } from '@vueuse/core'
const { isSupported, isConnected, device, requestDevice, server } =
  useBluetooth({
    acceptAllDevices: true,
    optionalServices: ['battery_service'],
  })
const batteryPercent = ref()
const isGettingBatteryLevels = ref(false)
async function getBatteryLevels() {
  isGettingBatteryLevels.value = true
  // Get the battery service:
  const batteryService = await server.getPrimaryService('battery_service')
  // Get the current battery level
  const batteryLevelCharacteristic =
    await batteryService.getCharacteristic('battery_level')
  // Listen to when characteristic value changes on `characteristicvaluechanged` event:
  batteryLevelCharacteristic.addEventListener(
    'characteristicvaluechanged',
    (event) => {
      batteryPercent.value = event.target.value.getUint8(0)
    },
  )
  // Convert received buffer to number:
  const batteryLevel = await batteryLevelCharacteristic.readValue()
  batteryPercent.value = await batteryLevel.getUint8(0)
}
const { stop } = pausableWatch(isConnected, (newIsConnected) => {
  if (!newIsConnected || !server.value || isGettingBatteryLevels.value) return
  // Attempt to get the battery levels of the device:
  getBatteryLevels()
  // We only want to run this on the initial connection, as we will use an event listener to handle updates:
  stop()
})

<template>
  <button @click="requestDevice()">
    Request Bluetooth Device
  </button>
</template>

更多样本可以在 Google Chrome 的网络蓝牙示例 上找到。

¥More samples can be found on Google Chrome's Web Bluetooth Samples.

类型声明

显示类型声明

export interface UseBluetoothRequestDeviceOptions {
  /**
   *
   * An array of BluetoothScanFilters. This filter consists of an array
   * of BluetoothServiceUUIDs, a name parameter, and a namePrefix parameter.
   *
   */
  filters?: BluetoothLEScanFilter[] | undefined
  /**
   *
   * An array of BluetoothServiceUUIDs.
   *
   * @see https://developer.mozilla.org/en-US/docs/Web/API/BluetoothRemoteGATTService/uuid
   *
   */
  optionalServices?: BluetoothServiceUUID[] | undefined
}
export interface UseBluetoothOptions
  extends UseBluetoothRequestDeviceOptions,
    ConfigurableNavigator {
  /**
   *
   * A boolean value indicating that the requesting script can accept all Bluetooth
   * devices. The default is false.
   *
   * !! This may result in a bunch of unrelated devices being shown
   * in the chooser and energy being wasted as there are no filters.
   *
   *
   * Use it with caution.
   *
   * @default false
   *
   */
  acceptAllDevices?: boolean
}
export declare function useBluetooth(
  options?: UseBluetoothOptions,
): UseBluetoothReturn
export interface UseBluetoothReturn {
  isSupported: Ref<boolean>
  isConnected: ComputedRef<boolean>
  device: Ref<BluetoothDevice | undefined>
  requestDevice: () => Promise<void>
  server: Ref<BluetoothRemoteGATTServer | undefined>
  error: Ref<unknown | null>
}

源代码

源代码 • 示例 • 文档

变更日志

No recent changes