实战分享：如何用srh-BluetoothAdapter插件，让UniApp X应用在鸿蒙NEXT上稳定连接蓝牙设备
实战分享：如何用srh-BluetoothAdapter插件，让UniApp X应用在鸿蒙NEXT上稳定连接蓝牙设备
在跨平台开发领域，UniApp X凭借其"一次开发，多端部署"的特性，正成为越来越多开发者的首选。而随着鸿蒙NEXT系统的崛起，如何让UniApp X应用在鸿蒙生态中充分发挥硬件交互能力，尤其是蓝牙连接这类核心功能，成为开发者面临的新挑战。本文将深入剖析srh-BluetoothAdapter这一社区优质插件，手把手带你实现鸿蒙NEXT平台下的蓝牙设备稳定连接与数据交互。
1. 环境准备与插件选型
1.1 开发环境配置
要开始鸿蒙NEXT的蓝牙开发，首先需要确保开发环境满足以下要求：
- HBuilderX 4.61+：这是UniApp X开发的基础IDE
- DevEco Studio 5.0.7.210+：鸿蒙官方开发工具，用于本地编译
- 鸿蒙手机系统API 14+：可通过手机设置中的"关于本机"查看
提示：与传统的UniApp基于JS的热刷新不同，UniApp X编译到鸿蒙后运行在ArkTS引擎上，每次代码修改都需要重新build和安装，建议使用真机调试提升效率。
1.2 插件核心优势分析
srh-BluetoothAdapter插件之所以成为鸿蒙蓝牙开发的首选，主要基于以下几点优势：
| 特性 | 传统方案 | srh-BluetoothAdapter |
|---|---|---|
| 开发效率 | 需要从零实现原生调用 | 提供即用型API封装 |
| 兼容性 | 需要处理多平台差异 | 统一UniApp和鸿蒙调用方式 |
| 功能完整性 | 需自行实现各蓝牙操作 | 覆盖发现、连接、读写全流程 |
| 社区支持 | 依赖官方文档 | 有活跃的问题反馈和更新 |
2. 权限配置与初始化
2.1 蓝牙权限声明
鸿蒙系统对蓝牙等敏感权限有严格管控，需要在module.json5中正确声明：
{ "module": { "requestPermissions": [ { "name": "ohos.permission.ACCESS_BLUETOOTH", "reason": "$string:bluetooth_desc" }, { "name": "ohos.permission.APPROXIMATELY_LOCATION", "reason": "$string:location_desc" } ] } }对应的string.json中需要定义提示信息：
{ "string": [ { "name": "bluetooth_desc", "value": "需要蓝牙权限以连接您的智能设备" } ] }2.2 动态权限申请
使用配套的srh-openPermission插件实现优雅的权限申请：
import { openPermission } from '@/uni_modules/srh-openPermission'; async function checkBluetoothPermission() { const status = await openPermission('ohos.permission.ACCESS_BLUETOOTH'); if (status !== 0) { console.warn('蓝牙权限未授权'); return false; } return true; }3. 蓝牙设备连接实战
3.1 设备发现与筛选
通过startBluetoothDevicesDiscovery开启设备扫描：
$uni.startBluetoothDevicesDiscovery({ success: (res) => { console.log('开始搜索设备', res); }, fail: (err) => { console.error('搜索失败', err); } }); // 监听发现设备事件 $uni.onBluetoothDeviceFound((devices) => { const targetDevice = devices.find(device => device.name?.includes('YourDevicePrefix') ); if (targetDevice) { this.connectDevice(targetDevice.deviceId); } });3.2 稳定连接策略
createBLEConnection是连接的核心API，但实际应用中需要考虑重连机制：
let retryCount = 0; const MAX_RETRY = 3; async function connectDevice(deviceId: string) { try { await new Promise((resolve, reject) => { $uni.createBLEConnection({ deviceId, success: resolve, fail: reject }); }); retryCount = 0; console.log('连接成功'); } catch (err) { if (retryCount < MAX_RETRY) { retryCount++; setTimeout(() => connectDevice(deviceId), 1000); } else { console.error('连接失败', err); } } }4. 数据读写与性能优化
4.1 特征值读写操作
获取服务与特征值是数据交互的前提：
async function setupServices(deviceId: string) { const services = await $uni.getBLEDeviceServices({ deviceId }); const primaryService = services.find(s => s.isPrimary); if (primaryService) { const characteristics = await $uni.getBLEDeviceCharacteristics({ deviceId, serviceId: primaryService.uuid }); this.writeCharacteristic = characteristics.find(c => c.properties.write ); this.notifyCharacteristic = characteristics.find(c => c.properties.notify ); } }4.2 高效数据写入技巧
writeBLECharacteristicValue支持多种写入方式，根据场景选择：
// 普通写入（需要响应） $uni.writeBLECharacteristicValue({ deviceId, serviceId, characteristicId, value: new Uint8Array([0x01, 0x02]).buffer, writeType: 'write' }); // 无响应写入（更快但不可靠） $uni.writeBLECharacteristicValue({ deviceId, serviceId, characteristicId, value: new Uint8Array([0x03, 0x04]).buffer, writeType: 'writeNoResponse' });4.3 大数据分包处理
当需要传输较大数据时，需要实现分包逻辑：
const CHUNK_SIZE = 20; // 蓝牙单次传输限制 async function sendLargeData(deviceId: string, data: ArrayBuffer) { const chunks = []; for (let i = 0; i < data.byteLength; i += CHUNK_SIZE) { chunks.push(data.slice(i, i + CHUNK_SIZE)); } for (const [index, chunk] of chunks.entries()) { await $uni.writeBLECharacteristicValue({ deviceId, serviceId, characteristicId, value: chunk }); console.log(`已发送 ${index + 1}/${chunks.length}`); } }5. 实战案例：智能家居控制
在智能灯泡控制场景中，我们实现了完整的控制流程：
- 设备发现：扫描特定名称前缀的灯泡设备
- 特征值配置：识别亮度、色温等控制特征值
- 状态同步：通过notify特性实时获取设备状态
- 控制指令：发送16进制指令调节灯光参数
// 设置灯光颜色 function setLightColor(deviceId: string, hexColor: string) { const rgb = hexToRgb(hexColor); const buffer = new Uint8Array([0x56, rgb.r, rgb.g, rgb.b, 0x00, 0xF0, 0xAA]); $uni.writeBLECharacteristicValue({ deviceId, serviceId: LIGHT_SERVICE_UUID, characteristicId: COLOR_CHARACTERISTIC_UUID, value: buffer.buffer }); }在健康设备数据同步项目中，我们发现合理设置MTU能显著提升传输效率：
// 设置最大传输单元 $uni.setBLEMTU({ deviceId, mtu: 512, // 根据设备支持情况调整 success: () => console.log('MTU设置成功'), fail: (err) => console.warn('MTU设置失败', err) });