Web Bluetooth API 是浏览器提供的原生接口，允许网页直接与附近的低功耗蓝牙设备建立连接并交互数据，无需安装额外插件。目前主流的 Chrome、Edge 等浏览器已经支持该接口，不过需要在 HTTPS 环境下或者本地 localhost 环境中使用。
环境兼容性检查
在使用 Web Bluetooth API 之前，首先需要检查当前浏览器是否支持该接口，避免在不兼容的环境下执行相关代码导致报错。
// 检查浏览器是否支持 Web Bluetooth API
if ('bluetooth' in navigator) {
console.log('当前浏览器支持 Web Bluetooth API');
} else {
console.log('当前浏览器不支持 Web Bluetooth API，请更换 Chrome 或 Edge 浏览器');
}
扫描并连接低功耗蓝牙设备
使用 navigator.bluetooth.requestDevice 方法可以触发浏览器的设备扫描弹窗，让用户选择要连接的蓝牙设备。该方法支持通过过滤条件筛选目标设备，比如指定设备名称前缀、服务 UUID 等。
常用过滤参数说明
- filters：设备过滤规则数组，可以指定 name、namePrefix、services 等条件
- optionalServices：可选的服务 UUID 列表，即使不在过滤条件中也可以后续访问这些服务
- acceptAllDevices：是否接受所有设备，设置为 true 时会忽略 filters 条件，显示所有可连接的蓝牙设备
// 扫描并连接指定名称前缀的低功耗蓝牙设备
async function connectBluetoothDevice() {
try {
// 请求用户选择蓝牙设备，过滤名称前缀为 BLE_Device_ 的设备
const device = await navigator.bluetooth.requestDevice({
filters: [
{ namePrefix: 'BLE_Device_' }
],
optionalServices: ['battery_service', 'device_information']
});
console.log('选中的设备：', device.name);
// 连接设备
const server = await device.gatt.connect();
console.log('设备连接成功');
return { device, server };
} catch (error) {
console.error('连接设备失败：', error);
}
}
读写蓝牙设备的特征值
低功耗蓝牙设备的功能通过服务（Service）和特征值（Characteristic）来定义，连接设备后需要先获取目标服务，再获取对应的特征值，才能进行数据读写操作。
读取特征值数据
读取操作需要先获取特征值的读取权限，然后调用 readValue 方法获取二进制数据，再按照设备定义的格式解析数据。
// 读取电池电量服务的电量特征值
async function readBatteryLevel(server) {
try {
// 获取电池电量服务，UUID 为 0x180f
const service = await server.getPrimaryService('battery_service');
// 获取电量特征值，UUID 为 0x2a19
const characteristic = await service.getCharacteristic('battery_level');
// 读取特征值数据
const value = await characteristic.readValue();
// 解析数据，电池电量值为一个字节的无符号整数
const batteryLevel = value.getUint8(0);
console.log('当前电池电量：', batteryLevel, '%');
return batteryLevel;
} catch (error) {
console.error('读取电量失败：', error);
}
}
写入特征值数据
写入操作需要先确认特征值支持写入权限，然后将要写入的数据转换为 ArrayBuffer 格式，调用 writeValue 方法完成写入。
// 向指定特征值写入数据
async function writeDataToDevice(server, serviceUUID, characteristicUUID, data) {
try {
const service = await server.getPrimaryService(serviceUUID);
const characteristic = await service.getCharacteristic(characteristicUUID);
// 检查特征值是否支持写入
if (characteristic.properties.write || characteristic.properties.writeWithoutResponse) {
// 将字符串转换为 ArrayBuffer
const encoder = new TextEncoder();
const dataBuffer = encoder.encode(data);
await characteristic.writeValue(dataBuffer);
console.log('数据写入成功');
} else {
console.log('该特征值不支持写入操作');
}
} catch (error) {
console.error('写入数据失败：', error);
}
}
监听蓝牙设备特征值变化
部分蓝牙设备的特征值会主动更新数据，比如传感器设备的实时数据，此时可以通过 startNotifications 方法开启特征值变化监听，当数据更新时会触发对应的事件回调。
// 监听温度特征值的变化
async function listenTemperatureChange(server, serviceUUID, characteristicUUID) {
try {
const service = await server.getPrimaryService(serviceUUID);
const characteristic = await service.getCharacteristic(characteristicUUID);
// 开启通知
await characteristic.startNotifications();
// 监听特征值变化事件
characteristic.addEventListener('characteristicvaluechanged', (event) => {
const value = event.target.value;
// 假设温度数据为两个字节的有符号整数，单位为 0.1℃
const temperature = value.getInt16(0, true) / 10;
console.log('当前温度：', temperature, '℃');
});
console.log('已开始监听温度数据变化');
} catch (error) {
console.error('开启监听失败：', error);
}
}
断开蓝牙设备连接
当不需要再与设备通信时，需要及时断开连接释放资源，同时可以监听设备的断开事件，处理连接意外断开的情况。
// 断开设备连接并监听断开事件
function disconnectDevice(device) {
if (device.gatt.connected) {
device.gatt.disconnect();
console.log('设备已主动断开连接');
}
// 监听设备断开事件
device.addEventListener('gattserverdisconnected', () => {
console.log('设备连接已断开，可能是设备关机或超出通信范围');
});
}
常见注意事项
- Web Bluetooth API 必须在 HTTPS 环境或者 localhost 本地环境中使用，普通 HTTP 页面无法调用
- 设备扫描和连接操作必须由用户主动触发，比如点击按钮事件，不能在页面加载时自动执行
- 不同的蓝牙设备服务 UUID 和特征值 UUID 不同，需要参考对应设备的通信协议文档
- 蓝牙通信有距离限制，超出范围后会自动断开连接，需要做好重连机制
Web_Bluetooth_API低功耗蓝牙蓝牙通信前端开发修改时间：2026-06-27 01:57:46