更新记录

1.0.0（2026-04-02）

• 初始版本
• 支持设备搜索、连接、绑定登录
• 支持健康数据监听间隔设置（心率、血氧、HRV、压力、血糖）
• 支持实时健康数据检测
• 支持历史健康数据同步
• 支持设备控制（查找、关机、恢复出厂）

平台兼容性

uni-app(4.81)

uni-app x(4.82)

hl-rwble-ring

RW BLE 手环/戒指 UTS 插件，封装 RW 官方蓝牙可穿戴 SDK（Android AAR / iOS Framework），适用于 uni-app App 端：设备发现与连接、绑定与时间、健康全天监听、单次测量、历史同步、戒指扩展能力（视频手势、LED、拍照触发）等。

目录

• 平台与环境
• 快速开始
• 类型说明
• API 一览
• 调用示例（按场景）
• 历史同步 onData 类型说明
• 完整示例工程
• 注意事项
• 目录结构
• 相关链接

平台与环境

官方说明：UTS Android 运行 · UTS iOS 插件

快速开始

1. 导入（推荐命名空间，避免与其它模块同名导出冲突）

import * as RwBleRing from '@/uni_modules/hl-rwble-ring'

2. 初始化与日志（建议在应用启动或进入蓝牙页时调用）

RwBleRing.initSDK()

RwBleRing.enableDebugLog((level, tag, message) => {
  console.log(`[${level}] ${tag}: ${message}`)
})

3. 退出页面时释放（可选，避免重复初始化或泄漏）

import { onUnmounted } from 'vue'

onUnmounted(() => {
  RwBleRing.destroySDK()
})

类型说明

以下与 utssdk/interface.uts 一致；复杂结构在运行时多为 UTSJSONObject，用 中括号 访问字段，例如 result.data['power']。

RwBleDevice

RwConnectionEvent

RwResult（多数指令回调）

RwHealthRealtimeData（单次检测实时值）

RwSyncOptions（历史同步）

健康业务类型 healthType（字符串）

统一用于监听设置、单次检测启停：

API 一览

调用示例（按场景）

扫描与连接

RwBleRing.startScan(
  (device) => {
    console.log(device.name, device.mac, device.rssi)
  },
  () => {
    console.log('扫描结束')
  },
  (code, msg) => {
    console.error('扫描失败', code, msg)
  }
)

RwBleRing.stopScan()

RwBleRing.connectDevice(mac, name, (event) => {
  if (event.status == 'connected') {
    console.log('已连接', event.device)
  } else if (event.status == 'disconnected') {
    console.log('已断开')
  } else if (event.status == 'error' || event.status == 'timeout') {
    console.log('连接异常', event.errorCode)
  }
})

RwBleRing.disconnectDevice()
const ok = RwBleRing.isDeviceConnected()

绑定、时间、固件、电量

// bindType / userId 请按 RW SDK 文档与业务约定填写；以下为演示占位
RwBleRing.loginDevice(1, '1000', (result) => {
  if (result.code == 0) {
    console.log('登录成功')
  }
})

RwBleRing.setTime(8) // UTC+8

RwBleRing.getFirmwareInfo((result) => {
  if (result.code == 0 && result.data != null) {
    const d = result.data
    console.log(d['deviceClass'], d['deviceNo'], d['uiVersion'])
  }
})

RwBleRing.getPower((result) => {
  if (result.code == 0 && result.data != null) {
    console.log('电量', result.data['power'])
  }
})

全天监听：获取 / 设置

获取为异步，建议在回调里关闭 uni.showLoading。

const healthType = 'heartRate'

uni.showLoading({ title: '读取中…', mask: true })
RwBleRing.getHealthMonitor(healthType, (result) => {
  uni.hideLoading()
  if (result.code == 0 && result.data != null) {
    const d = result.data
    const isOpen = d['isOpen'] == true || d['isOpen'] == 1
    const minutes = d['intervalMinutes']
    console.log('开启', isOpen, '间隔', minutes)
  }
})

// 开启监听，间隔 60 分钟（设备不支持的时间会被 SDK 处理）
RwBleRing.setHealthMonitor(healthType, true, 60, (result) => {
  console.log(result.message, result.code)
})

佩戴位置

RwBleRing.getWearPosition((result) => {
  if (result.code == 0 && result.data != null) {
    const right = result.data['isRightHand']
    console.log(right ? '右手' : '左手')
  }
})

RwBleRing.setWearPosition(false, (result) => {
  console.log(result.message)
}) // 左手

单次健康检测（实时值 + 结束回调）

RwBleRing.startHealthTest(
  'heartRate',
  (data) => {
    console.log(data.dataType, data.value)
  },
  (result) => {
    console.log('控制结果', result.message)
  }
)

RwBleRing.stopHealthTest('heartRate', (result) => {
  console.log('停止', result.message)
})

视频手势、LED、拍照

RwBleRing.getVideoHid((result) => {
  if (result.code == 0 && result.data != null) {
    console.log('视频手势', result.data['isOpen'])
  }
})
RwBleRing.setVideoHid(true, (result) => console.log(result.message))

RwBleRing.getLedLevel((result) => {
  if (result.code == 0 && result.data != null) {
    console.log(result.data['isOpen'], result.data['lcdLevel'])
  }
})
RwBleRing.setLedLevel(true, 2, (result) => console.log(result.message))

RwBleRing.startTakePhoto(
  (result) => console.log('模式', result.message),
  (action) => {
    if (action == 2) {
      // 调起相机或业务拍照
      console.log('设备触发拍照')
    }
  }
)
RwBleRing.stopTakePhoto()

查找 / 关机 / 恢复出厂

RwBleRing.findDevice()

RwBleRing.powerOff()
RwBleRing.factoryReset()

历史同步

RwBleRing.syncHealthData({
  supportStress: true,
  supportBloodSugar: true,
  supportMuslimPraise: false,
  : (p) => console.log('进度', p),
  onFinish: () => console.log('完成'),
  onError: (code) => console.error('错误', code),
  onData: (dataType, list) => {
    console.log(dataType, list.length)
    for (let i = 0; i < list.length; i++) {
      const row = list[i]
      // 按 dataType 解析 row['date']、row['hr'] 等，见下节
    }
  }
})

历史同步 onData 类型说明

dataType 由原生 SDK 回调决定，不同固件/协议可能略有差异。当前插件常见取值如下（仅供参考，以真机为准）：

每条元素为 UTSJSONObject，字段名随类型不同（如心率常见 date、time、hr；计步常见 date、step、distance、calorie）。杰理睡眠等协议可能仅含 time、sleepModel 等，需按 RW 文档解析。

完整示例工程

仓库内演示页：pages/ring-demo/index.vue

覆盖能力概览：

• 扫描列表、连接/断开、登录、对时
• 固件、电量
• 五项健康监听获取/设置（含 uni.showLoading）
• 佩戴位置、实时检测、视频 HID、LED、拍照
• 查找/关机/恢复出厂
• syncHealthData 基础同步与扩展项
• onUnmounted 中 destroySDK()

可直接对照该文件复制业务代码片段。

注意事项

1. 自定义基座
   含三方原生库，真机调试需使用自定义调试基座或云端正式包，标准基座无法加载插件原生部分。

2. 调用顺序
   建议先 initSDK()，再扫描/连接；多数指令需已连接设备后再调用（与官方 Demo 一致）。

3. 异步与 UI
   getHealthMonitor、getFirmwareInfo、getPower 等均在蓝牙交互完成后才回调，耗时数百毫秒～数秒属正常；长时间操作建议 showLoading 并在回调里 hideLoading。

4. RwResult.data 访问
   使用 result.data['field']；判断存在用 result.data != null。iOS 侧失败时 不会 向 data 写入 NSNull，避免强转崩溃。

5. isOpen 等布尔含义字段
   桥接后可能是 number（0/1），判断时建议兼容：val == true || val == 1（与演示页 parseMonitorData 一致）。

6. setTime / loginDevice 参数
   时区、绑定类型与用户 ID 以 RW 官方 PDF / Demo 为准；演示中 loginDevice(1, '1000') 仅为占位。

7. 单次检测
   startHealthTest 的 onResult 多为启动指令应答；实时数值走 onRealtimeData。iOS 侧测量结束由通知驱动，请勿假设 onResult 会多次携带完整流程（详见插件内注释）。

8. UTS 与 Vue
   插件内部已对需长期持有的回调使用 @UTSJS.keepAlive 等处理；业务侧避免在回调里引用已销毁的页面实例。

9. 同步选项
   supportStress / supportBloodSugar / supportMuslimPraise 需设备与固件支持；否则可能无对应 onData 或报错码。

10. 权限
    Android 需蓝牙/定位等系统授权；iOS 需在系统设置中允许蓝牙，且包内包含蓝牙使用说明（插件已提供 Info.plist 模板）。