更新记录
1.0.0(2026-11-18)
第一版
平台兼容性
uni-app(4.51)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | - | - | √ | √ | 6.0 | 15 | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | - | - | - | - | - | - |
uni-app x(4.51)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | 6.0 | 15 | √ | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
wen-bluetooth
BLE 扫描、连接、服务读写、通知订阅、广播与设备协议处理。
功能介绍
- 扫描、过滤、连接、断开及连接状态事件。
- GATT 服务与特征枚举,读取、写入和通知订阅。
- 广播、信标解析、RSSI、设备状态与恢复配置。
- 示例包含 BLE 工作台、设备识别与已开放的指令流程。
平台兼容性
| 项目 | 要求 |
|---|---|
| HBuilderX | 5.26 或更新版本 |
| uni-app / uni-app x | Vue 3;原生 App |
| Android | API 23 起;部分系统能力有更高版本要求 |
| iOS | 16.2 起;以设备能力及宿主配置为准 |
| HarmonyOS | 使用 app-harmony 源码及其声明的 SDK / 权限 |
| Web / 小程序 | 不提供原生能力 |
插件测试使用方法
- 在插件市场绑定自己的项目 AppID,将插件导入项目的
uni_modules/wen-bluetooth。本地使用时也可直接复制完整插件目录。 - 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
- 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
- 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
- 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 Key、Token、账号密码或签名私钥。
使用示例
import { nativeBluetoothRequest } from '@/uni_modules/wen-bluetooth'
nativeBluetoothRequest('capabilities', JSON.stringify({}), (raw: string) => {
const result = JSON.parseObject(raw)
if (result == null) return
if (result.getNumber('code') != 0) {
uni.showToast({ title: result.getString('message') ?? '操作失败', icon: 'none' })
return
}
console.log(result['data'])
})
API 介绍
原生入口接收 operation、JSON 字符串 payload 和回调。回调统一返回 { code, message?, data? };code 为 0 表示成功。
nativeBluetoothRequest
nativeBluetoothRequest(operation:string,payload:string,done:(result:string)=>void):void
配置参数
配置通过打开/启动操作传入;其他操作参数以示例调用为准。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
maxConnections |
number | 4 |
并发连接上限;最小 1;最大 8 |
connectTimeoutMs |
number | 20000 |
连接超时(毫秒);最小 3000;最大 60000 |
operationTimeoutMs |
number | 12000 |
GATT / 串口操作超时;最小 1000;最大 30000 |
scanTimeoutMs |
number | 15000 |
扫描时长;最小 1000;最大 120000 |
reconnect |
boolean | true |
断线后自动重连 |
reconnectBaseMs |
number | 1000 |
重连初始间隔;最小 500;最大 10000 |
reconnectMaxMs |
number | 30000 |
重连最大间隔;最小 1000;最大 300000 |
reconnectAttempts |
number | 8 |
每轮重连次数;最小 0;最大 30 |
requestedMtu |
number | 247 |
期望 MTU;最小 23;最大 517 |
writeChunkSize |
number | 180 |
单包写入上限;最小 1;最大 512 |
interChunkDelayMs |
number | 15 |
分包间隔;最小 0;最大 1000 |
queueLimit |
number | 64 |
操作队列上限;最小 1;最大 256 |
autoDiscover |
boolean | true |
连接后自动发现服务 |
restoreSubscriptions |
boolean | true |
重连后恢复订阅 |
eventLimit |
number | 1000 |
事件保留条数;最小 100;最大 5000 |
scanLimit |
number | 200 |
扫描设备上限;最小 10;最大 500 |
persistDataEvents |
boolean | false |
持久保存收发原始数据 |
foregroundTitle |
string | "蓝牙设备连接中" |
后台通知标题 |
foregroundText |
string | "保持已授权设备的连接与数据收发" |
后台通知说明 |
foregroundSubText |
string | "" |
通知附加说明 |
foregroundChannelName |
string | "蓝牙后台连接" |
通知渠道名称 |
foregroundChannelDescription |
string | "维持用户授权的蓝牙连接;可从通知停止" |
通知渠道说明 |
foregroundStopText |
string | "停止并断开" |
停止按钮文案 |
foregroundColor |
string | "" |
通知强调色 |
foregroundIconResource |
string | "" |
通知小图标资源 |
foregroundShowWhen |
boolean | false |
显示启动时间 |
foregroundChronometer |
boolean | false |
显示持续计时 |
foregroundVisibility |
string | "private" |
锁屏可见性 |
foregroundOpenApp |
boolean | true |
点击通知打开应用 |
JavaScript 封装接口
普通 uni-app 页面可使用插件目录中的 client.js。调用前先完成平台权限申请;异步操作用 await / catch 处理。具体参数类型见同目录的 client.d.ts 或 index.d.ts。
createBluetoothClient
createBluetoothClient(transport) 返回的方法:
| 方法与参数 | 原生 operation |
|---|---|
deviceIdentify(p) |
deviceIdentify |
deviceProfileCatalog() |
deviceProfileCatalog |
deviceAction(p) |
deviceAction |
ecosystemCatalog() |
ecosystemCatalog |
mediaAccess() |
mediaAccess |
mediaSettings() |
mediaSettings |
mediaSessions() |
mediaSessions |
mediaVolume() |
mediaVolume |
mediaCommand(p) |
mediaCommand |
mediaVolumeSet(p) |
mediaVolumeSet |
mediaWatch() |
mediaWatch |
mediaUnwatch() |
mediaUnwatch |
workflowTemplates() |
workflowTemplates |
workflowSave(p) |
workflowSave |
workflowRemove(name) |
workflowRemove |
workflowStart(p) |
workflowStart |
workflowCancel() |
workflowCancel |
workflowStatus() |
workflowStatus |
nativeUiCapabilities() |
nativeUiCapabilities |
notificationConfig() |
notificationConfig |
notificationConfigure(p) |
notificationConfigure |
deviceCatalog() |
deviceCatalog |
compatibilityAnalyze(p) |
compatibilityAnalyze |
featureCatalog() |
featureCatalog |
advertisementDecode(hex) |
advertisementDecode |
beaconEncode(p) |
beaconEncode |
broadcastStart(p) |
broadcastStart |
broadcastUpdate(p) |
broadcastUpdate |
broadcastStop() |
broadcastStop |
backgroundScanStart(p) |
backgroundScanStart |
backgroundScanStop() |
backgroundScanStop |
backgroundScanStatus() |
backgroundScanStatus |
hidStart(p) |
hidStart |
hidConnect(address) |
hidConnect |
hidKey(p) |
hidKey |
hidText(text) |
hidText |
hidMouse(p) |
hidMouse |
hidMedia(command) |
hidMedia |
hidRelease() |
hidRelease |
hidDisconnect() |
hidDisconnect |
hidStop() |
hidStop |
hidStatus() |
hidStatus |
capabilities() |
capabilities |
permissions() |
permissions |
status() |
status |
diagnostics() |
diagnostics |
configure(p) |
configure |
requestPermission(kind='scan') |
requestPermission |
settings(kind='bluetooth') |
settings |
requestEnable() |
requestEnable |
scan(p) |
scan |
stopScan() |
stopScan |
bondedDevices() |
bondedDevices |
pair(address) |
pair |
fetchUuids(address) |
fetchUuids |
connect(p) |
connect |
disconnect(connectionId, {forget=true}={}) |
disconnect |
disconnectAll() |
disconnectAll |
reliableWrite(connectionId, writes) |
reliableWrite |
services(connectionId) |
services |
discover(connectionId) |
discover |
read(connectionId, p) |
read |
write(connectionId, p) |
write |
subscribe(connectionId, p) |
subscribe |
readDescriptor(connectionId, p) |
readDescriptor |
writeDescriptor(connectionId, p) |
writeDescriptor |
mtu(connectionId, mtu=247) |
mtu |
rssi(connectionId) |
rssi |
priority(connectionId, priority='balanced') |
priority |
socketWrite(connectionId, hex) |
socketWrite |
backgroundStart({consent=false}={}) |
backgroundStart |
backgroundStop() |
backgroundStop |
profiles() |
profiles |
restore() |
restoreProfiles |
forgetProfile(address) |
forgetProfile |
events(afterId=0, limit=100) |
events |
clearEvents() |
clearEvents |
peripheralStart(p) |
peripheralStart |
peripheralUpdate(p) |
peripheralUpdate |
peripheralStop() |
peripheralStop |
serverStart(p) |
serverStart |
serverStop() |
serverStop |
audioProfiles() |
audioProfiles |
audioRoutes() |
audioRoutes |
audioRoute(p) |
audioRoute |
protocols() |
protocols |
decode(profile, hex) |
protocolDecode |
encode(profile, p={}) |
protocolEncode |
companionList() |
companionList |
companionAssociate(p) |
companionAssociate |
companionObserve(address, enabled=true) |
companionObserve |
companionDisassociate(p) |
companionDisassociate |
subscribeEvents(listener, {afterId=0,intervalMs=700,onError=()=>{}}={}) |
events |
在项目页面中定制
场景预设、按钮排版、页面文案和配色由示例项目的 pages 目录及项目自身的公共文件管理;安装插件不需要接收这些页面。可以直接修改页面,或按自己的设计重新编写。插件只提供原生能力、参数默认值及校验,不再导出业务 PRESETS。
配置函数只接收配置对象,不接收场景名称;多种预设在页面里定义,再把对象传入。未提供的字段由插件补齐默认值。
import { createBluetoothConfig } from '@/uni_modules/wen-bluetooth/client.js'
// 这份对象写在自己的页面里,字段值可由表单或业务数据产生。
const options = { scanTimeoutMs: 10000, foregroundTitle: '我的设备' }
const config = createBluetoothConfig(options)
使用注意
- 系统权限根据 Android 版本分别申请附近设备或位置权限,扫描前检查系统蓝牙开关。
- GATT UUID、设备协议与可用动作由目标外设决定,不能依据品牌推断型号兼容。
- 未完成设备验收的厂商 SDK、OTA、HID 和高级传输入口不在发布示例中展示。
- iOS 配对及后台行为由系统管理,接口能力与 Android 不完全相同。
隐私、权限声明
1. 本插件需要申请的系统权限列表
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE"/>
<uses-permission android:name="android.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE"/>
<uses-permission android:name="android.permission.REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND"/>
iOS 用途说明在 app-ios/Info.plist 中,鸿蒙权限在 app-harmony/module.json5 中;宿主仍需按实际业务说明用途并配置能力。
2. 本插件采集的数据、发送的服务器地址、以及数据用途说明
处理附近设备广播、设备标识、连接状态及用户主动读写的数据。使用厂商账号或 SDK 服务时需由应用另行告知并取得授权。
3. 本插件是否包含广告
不包含广告。

收藏人数:
购买源码授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 18
赞赏 0
下载 12771027
赞赏 1959
赞赏
京公网安备:11010802035340号