useBluetooth
响应式的 Web 蓝牙 API。提供与蓝牙低功耗外围设备连接和交互的能力。
Web 蓝牙 API 允许网站使用通用属性配置文件 (GATT) 在蓝牙 4 无线标准上发现和通信设备。
注意：它目前在 Android M、Chrome OS、Mac 和 Windows 10 中部分实现。有关浏览器兼容性的完整概述，请参阅 Web 蓝牙 API 浏览器兼容性。
注意：关于 Web 蓝牙 API 规范，有一些需要注意的事项。请参阅 Web 蓝牙 W3C 草案报告以获取关于设备检测和连接的众多注意事项。
注意：此 API 在 Web Workers 中不可用 (不通过 WorkerNavigator 暴露)。
示例
Your browser does not support the Bluetooth Web API
未连接
默认用法
vue
<script setup lang="ts">
import { useBluetooth } from '@vueuse/core'
const {
isSupported,
isConnected,
device,
requestDevice,
server,
error,
} = useBluetooth({
acceptAllDevices: true,
})
</script>
<template>
<button @click="requestDevice()">
请求蓝牙设备
</button>
<div v-if="error">
错误: {{ error }}
</div>
</template>返回值
| 属性 | 类型 | 说明 |
|---|---|---|
isSupported | ComputedRef<boolean> | 是否支持 Web 蓝牙 API |
isConnected | Ref<boolean> | 当前是否有设备连接 |
device | Ref<BluetoothDevice> | 已连接的蓝牙设备 |
server | Ref<BluetoothRemoteGATTServer> | 已连接设备的 GATT 服务器 |
error | Ref<unknown> | 连接过程中产生的任何错误 |
requestDevice | () => Promise<void> | 请求蓝牙设备的函数 |
当设备已配对并连接时，你可以自由地使用 server 对象。
电池电量示例用法
此示例演示了使用 Web 蓝牙 API 读取电池电量并从附近的蓝牙低功耗设备接收更改通知的方法。
在此示例中，我们使用 characteristicvaluechanged 事件侦听器来处理读取电池电量特征值。此事件侦听器还将选择性地处理即将到来的通知。
vue
<script setup lang="ts">
import { useBluetooth, useEventListener, watchPausable } 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
// 获取电池服务：
const batteryService = await server.getPrimaryService('battery_service')
// 获取当前电池电量特征值
const batteryLevelCharacteristic = await batteryService.getCharacteristic(
'battery_level',
)
// 监听 'characteristicvaluechanged' 事件，响应特征值变化：
useEventListener(batteryLevelCharacteristic, 'characteristicvaluechanged', (event) => {
batteryPercent.value = event.target.value.getUint8(0)
}, { passive: true })
// 将接收到的缓冲区转换为数字：
const batteryLevel = await batteryLevelCharacteristic.readValue()
batteryPercent.value = await batteryLevel.getUint8(0)
}
const { stop } = watchPausable(isConnected, (newIsConnected) => {
if (!newIsConnected || !server.value || isGettingBatteryLevels.value)
return
// 尝试获取设备的电池电量：
getBatteryLevels()
// 我们只希望在初次连接时运行此逻辑，之后通过事件监听处理更新：
stop()
})
</script>
<template>
<button @click="requestDevice()">
请求蓝牙设备
</button>
</template>更多示例可以在 Google Chrome 的 Web 蓝牙示例中找到。
类型声明
显示类型声明
ts
export interface UseBluetoothRequestDeviceOptions {
/**
*
* BluetoothScanFilters 的数组。
* 此过滤器由 BluetoothServiceUUIDs 数组、名称参数和名称前缀参数组成。
*
*/
filters?: BluetoothLEScanFilter[] | undefined
/**
*
* BluetoothServiceUUIDs 的数组。
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/BluetoothRemoteGATTService/uuid
*
*/
optionalServices?: BluetoothServiceUUID[] | undefined
}
export interface UseBluetoothOptions
extends UseBluetoothRequestDeviceOptions, ConfigurableNavigator {
/**
*
* 一个布尔值，指示请求脚本是否可以接受所有蓝牙设备。
* 默认值为 false。
*
* !! 这可能导致选择器中显示大量无关的设备，
* 并因为没有过滤器而浪费能量。
*
*
* 使用时要谨慎。
*
* @default false
*
*/
acceptAllDevices?: boolean
}
export declare function useBluetooth(
options?: UseBluetoothOptions,
): UseBluetoothReturn
export interface UseBluetoothReturn extends Supportable {
isConnected: Readonly<ShallowRef<boolean>>
device: ShallowRef<BluetoothDevice | undefined>
requestDevice: () => Promise<void>
server: ShallowRef<BluetoothRemoteGATTServer | undefined>
error: ShallowRef<unknown | null>
}源码
贡献者
一纸忘忧