更新记录

1.0.4（2026-06-11）

优化

平台兼容性

uni-app(4.03)

uni-app x(3.97)

其他

xtf-bleserver

BLE 低功耗蓝牙服务端插件，当前已提供 Android、iOS 和 HarmonyOS 的 App 端实现。

说明：

1. 这是 BLE 外设/服务端插件，适合让手机、开发板或模拟设备作为 BLE Server 对外广播。
2. 插件依赖原生能力，调试和运行请使用自定义基座。
3. 当前对外 API 已改为 export function 形式，不再使用 xtf 类静态方法。

支持平台

• uni-app x App Android
• uni-app x App iOS
• uni-app x App HarmonyOS

使用前准备

1. 选择试用并绑定项目 appid。
2. 下载插件到本地项目。
3. 云打包生成自定义基座。
4. 运行时选择对应平台的自定义基座。
5. 如果之前装过旧基座，先卸载再安装新基座。

导出 API

import {
  RecData,
  prepare,
  start,
  stop,
  sendBackDataToClient
} from '@/uni_modules/xtf-bleserver'

prepare(name, callback)

初始化 BLE 服务端。

• name: string 广播名称
• callback: (res: boolean) => void 初始化结果回调

start(callback, callState)

开始广播并监听客户端写入与连接状态变化。

• callback: (data: RecData) => void 收到客户端写入数据时触发
• callState: (mac: string, state: number) => void 连接状态变化时触发

stop()

停止 BLE 广播。

sendBackDataToClient(data)

向当前连接的客户端回发数据。

• data: string 16 进制字符串，例如 AABBCCDD

数据结构

export type RecData = {
  mac: string
  data: string
}

字段说明：

• mac：客户端标识
• data：收到的数据，格式为 16 进制字符串

uni-app x 示例

import {
  RecData,
  prepare,
  sendBackDataToClient,
  start,
  stop
} from '@/uni_modules/xtf-bleserver'

prepare('ble', function(res:boolean) {
  console.log('prepare', res)
})

start(function(data: RecData) {
  console.log('receive', data)
  // 收到什么回什么
  sendBackDataToClient(data.data)
}, function(mac: string, state: number) {
  console.log('state', mac, state)
})

stop()

连接状态说明

当前插件透传底层状态值，不同平台含义可能略有差异，实际请以真机测试为准。

UUID 说明

• Service UUID: 000000FF-0000-1000-8000-00805F9B34FB
• Write UUID: 0000FE01-0000-1000-8000-00805F9B34FB
• Notify UUID: 0000FE03-0000-1000-8000-00805F9B34FB

当前 Android、iOS 与 HarmonyOS 已统一使用同一套 UUID，客户端可按同一规则接入。

客户端如何连接

客户端连接本插件时，可按下面顺序处理：

1. 扫描广播，按广播名或 Service UUID 000000FF-0000-1000-8000-00805F9B34FB 过滤设备。
2. 连接设备后，发现 Service UUID 000000FF-0000-1000-8000-00805F9B34FB。
3. 找到写入特征 0000FE01-0000-1000-8000-00805F9B34FB，将业务数据按 16 进制对应的字节写入。
4. 找到通知特征 0000FE03-0000-1000-8000-00805F9B34FB，先订阅通知。
5. 服务端收到写入后，如果调用了 sendBackDataToClient(...)，客户端会从通知特征收到回包。

约定说明：

1. 插件回调中的 data 是大写 16 进制字符串。
2. sendBackDataToClient(data) 也要求传入 16 进制字符串，长度应为偶数。
3. 如果客户端未订阅 Notify 特征，服务端回发数据不会到达客户端。
4. iOS 侧回调中的 mac 实际是中心设备标识字符串，不是物理 MAC。
5. HarmonyOS 侧存在已知兼容性差异：部分 BLE 客户端在“订阅通知”步骤可能返回失败或显示失败，但服务端与客户端之间仍可正常收发消息，实际请以是否收到通知数据为准。

平台差异说明

Android

1. 会尝试设置蓝牙广播名称。
2. 依赖原生 AAR，必须使用自定义基座。
3. 当前已内置 16 进制字符串与 ByteArray 的转换逻辑。

iOS

1. iOS 返回的 mac 实际是 CBCentral.identifier.uuidString，不是物理 MAC 地址。
2. iOS 不能像 Android 一样直接修改系统蓝牙名称，prepare(name) 使用的是广播包本地名称。
3. sendBackDataToClient 依赖客户端已订阅通知特征后才能正常回发。
4. 同样需要自定义基座与蓝牙权限配置。

HarmonyOS

1. 当前为基于原生混编 .ets 的最小实现。
2. 对外 API 与 Android、iOS 保持一致：prepare、start、stop、sendBackDataToClient。
3. mac 字段在 HarmonyOS 侧同样表示连接端标识，不保证是物理 MAC 地址。
4. 需要鸿蒙蓝牙权限声明，插件内已补 app-harmony/module.json5，并会在 prepare(...) 时主动申请蓝牙权限。
5. 由于本地知识库缺少完整 BLE Peripheral 权威样例，个别底层事件名与签名需要以真实编译结果为准。
6. 当前已确认存在订阅状态兼容性差异：某些鸿蒙 BLE 客户端连接服务端后，订阅 Notify 特征时可能提示失败，但实际仍可以正常接收服务端回发的数据，也可以继续向服务端写入数据。
7. 因此在 HarmonyOS 场景下，建议业务侧不要只依赖“订阅调用返回值”判断是否可用，应结合真实消息收发结果共同判断。

注意事项

1. App 平台蓝牙能力必须在真机测试。
2. 使用前请确认系统蓝牙已开启。
3. Android 首次运行会申请蓝牙相关权限。
4. 发送数据时请传入合法偶数长度的 16 进制字符串。
5. 无客户端连接或客户端未订阅通知时，回发数据可能无效。
6. HarmonyOS 平台如遇到“订阅通知失败”但仍能正常收到消息，属于当前已知兼容性现象，不代表数据链路不可用。

开发文档

• UTS 语法
• UTS API 插件
• UTS uni-app 兼容模式组件
• UTS 标准模式组件
• Hello UTS