更新记录

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 扫描、连接、服务读写、通知订阅、广播与设备协议处理。

功能介绍

  1. 扫描、过滤、连接、断开及连接状态事件。
  2. GATT 服务与特征枚举,读取、写入和通知订阅。
  3. 广播、信标解析、RSSI、设备状态与恢复配置。
  4. 示例包含 BLE 工作台、设备识别与已开放的指令流程。

平台兼容性

项目 要求
HBuilderX 5.26 或更新版本
uni-app / uni-app x Vue 3;原生 App
Android API 23 起;部分系统能力有更高版本要求
iOS 16.2 起;以设备能力及宿主配置为准
HarmonyOS 使用 app-harmony 源码及其声明的 SDK / 权限
Web / 小程序 不提供原生能力

插件测试使用方法

  1. 在插件市场绑定自己的项目 AppID,将插件导入项目的 uni_modules/wen-bluetooth。本地使用时也可直接复制完整插件目录。
  2. 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
  3. 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
  4. 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
  5. 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 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. 本插件是否包含广告

不包含广告。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:CAMERA、RECORD_AUDIO,用于实时美颜预览、拍照和有声录像;集成的 Google ML Kit 相关依赖还涉及 INTERNET、ACCESS_NETWORK_STATE,用于 SDK 必要的网络通信和运行指标处理。 iOS:相机和麦克风授权,对应 NSCameraUsageDescription、NSMicrophoneUsageDescription。 HarmonyOS:CAMERA、MICROPHONE,用于相机画面及可选录像音轨采集。 自定义贴纸和三维素材通过应用提供的数据或系统授权的文件访问方式导入。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。