VueUse中文文档useBluetooth
响应式 Web Bluetooth API。提供连接低功耗蓝牙外设并与之交互的能力。
Reactive Web Bluetooth API. Provides the ability to connect and interact with Bluetooth Low Energy peripherals.
Web Bluetooth 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 Bluetooth API Browser Compatibility
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规范，有许多注意事项。有关设备检测和连接的注意事项，请参阅Web Bluetooth W3C Draft Report 。
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).
例子
未连接
Usage Default
import { useBluetooth } from '@vueuse/core'
const {
isSupported,
isConnected,
device,
requestDevice,
server,
} = useBluetooth({
acceptAllDevices: true,
})
import { useBluetooth } from '@vueuse/core'
const {
isSupported,
isConnected,
device,
requestDevice,
server,
} = useBluetooth({
acceptAllDevices: true,
})
<template>
<button @click="requestDevice()">
Request Bluetooth Device
</button>
</template>
<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 Bluetooth 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.
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)
const getBatteryLevels = async () => {
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',
)
// 监听 `characteristicvaluechanged` 事件
// 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<undefined | number>()
const isGettingBatteryLevels = ref(false)
const getBatteryLevels = async () => {
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',
)
// 监听 `characteristicvaluechanged` 事件
// 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>
<template>
<button @click="requestDevice()">
Request Bluetooth Device
</button>
</template>
更多的例子参见Google Chrome's Web Bluetooth Samples.
More samples can be found on Google Chrome's Web Bluetooth Samples.
类型声明(Type Declarations)
显示类型声明
/// <reference types="@types/web-bluetooth" />
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/zh-CN/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>
}
/// <reference types="@types/web-bluetooth" />
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/zh-CN/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>
}