更新记录

1.2.8（2026-09-07）

• 修复 Android：success/fail 回调 ClassCast（扁平 Option 不可强转为 BaseOption；入口去掉 coerce 重建）
• .vue 直接传对象；.uvue 须 as XxxOption；须重打自定义基座并云端传统打包
• 不传参行为与上一版兼容

1.2.7（2026-09-07）

• 优化 uni-app x：入口将对象字面量归一化为 Option，业务页可直接传对象调用 API，无需再写 as XxxOption
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 不传参行为与上一版兼容

1.2.6（2026-09-06）

• 修复协议 ArrayBuffer 转换：ByteArray.size Number.from
• 修复称重组帧协议：ByteArray.size/下标统一 Number.from 与 toInt
• 修复 App 端成功回调与驱动稳定性：去掉 undefined、可变属性强制解包改为局部拷贝；iOS BLE 状态/特性用 Number.from
• 修复 Android 运行时 ClassCastException：成功回调与 onWeight 结果改为 UTSJSONObject 别名，避免强转为独立 Result 类型
• 修复 Android 称重数据接收：共享会话对 ByteArray 使用 .size；去掉帧数组强制解包
• 修复 Android SPP 读循环：available/read 返回值先 Number.from 再比较
• 修复 Android BLE GATT 枚举：services/characteristics 的 size 先 Number.from 再循环
• 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-bleweight 使用说明

蓝牙电子秤接入插件，适用于收银、计件、巡检等连续称重场景。

当前版本：1.2.8

• Android：BLE 与经典蓝牙 SPP
• iOS / 鸿蒙 / 微信小程序：BLE
• 能力：可配置协议档与组帧；连续称重回调；去皮 / 置零 / 切单位 / 原始命令；getBondedDevices；有限退避重连
• 不做 USB/RS232 有线秤、不做通用 BLE 调试器、不做多秤并行连接池

建议调用顺序：init → startScan 或 getBondedDevices → connect → 接收 onWeight 或发控制命令 → disconnect / destroy。请先扫描（或取已配对列表）再连接。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 init 会销毁上一实例。

1. 环境要求

• HBuilderX 4.11 及以上
• uni-app Vue3（App-vue / App-nvue）或 uni-app x（App；微信能力与 uni-app 一致）
• 支持：App-Android、App-iOS、App-鸿蒙、微信小程序；uni-app 与 uni-app x（含 x 鸿蒙 BLE）
• 不支持：H5 及其它小程序
• Android 最低 API：21；iOS 最低 12；鸿蒙最低 API：12；微信小程序基础库建议 2.22.0 及以上
• App 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包
• 授权绑定唯一 appid + 包名

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-bleweight，或从插件市场导入后同步。

import {
  init,
  destroy,
  startScan,
  stopScan,
  connect,
  disconnect,
  getBondedDevices,
  getConnectionState,
  tare,
  zero,
  toggleUnit,
  sendRaw,
  getLastWeight,
} from '@/uni_modules/breao-bleweight'

// 联调或自研解析时可选导入（各端 app-* / 微信入口同样导出）：
// DEFAULT_NAME_HINTS、PROTOCOL_TEMPLATE_LIBRARY、appendAndExtractFrames、
// parseFrame、parseYaohuaStx、parseAsciiWw、parseTemplate、buildCommandBytes、
// applyThrottle、calcReconnectDelayMs

3. API

3.1 init / destroy

init({
  transport: 'ble', // Android 老秤可设 'spp'，详见 §4
  protocolProfile: 'yaohua_stx',
  onWeight(res) {
    console.log(res.weight, res.unit, res.stable)
  },
  onDisconnected(res) {
    console.log('disconnected', res)
  },
  success() {},
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

destroy({ success() {}, fail(err) { console.error(err.errCode, err.errMsg) } })

3.2 扫描与连接

startScan({
  timeout: 10000,
  success(res) {
    // res.devices: [{ name, address, rssi?, bonded? }]
  },
  fail(err) { console.error(err.errCode, err.errMsg) },
})

connect({
  address: 'XX:XX:XX:XX:XX:XX',
  success() {},
  fail(err) { console.error(err.errCode, err.errMsg) },
})

disconnect({ success() {}, fail() {} })
stopScan({ success() {}, fail() {} })

getBondedDevices({
  success(res) {
    // Android / 鸿蒙：res.devices 为系统已配对列表；iOS / 微信返回不支持
  },
  fail(err) { console.error(err.errCode, err.errMsg) },
})

请先扫描再连接（未扫描直接 connect 会返回中文错误「未找到该设备，请先扫描再连接」）；亦可先 getBondedDevices（Android/鸿蒙）再连。Android SPP 建议系统已配对。参数默认值见 §4。

3.3 控制命令

tare({ success() {}, fail() {} })
zero({ success() {}, fail() {} })
toggleUnit({ success() {}, fail() {} })
sendRaw({ data: 'RN1', success() {}, fail() {} })

命令内容取自 init 中的 tareCommand / zeroCommand / toggleUnitCommand；亦可用 sendRaw 发送任意 ASCII 串。

3.4 状态与最近称重

getConnectionState({
  success(res) {
    // res.state: disconnected | connecting | connected | busy
    // res.busy: 扫描/连接等互斥操作进行中时为 true
  },
})

getLastWeight({
  success(res) {
    // res.sample 为最近一次解析结果；尚无数据时为 null
  },
})

3.5 onWeight 字段

3.6 协议辅助（同步）

各端 index 均导出下列纯函数，供联调、离线解析或与插件内组帧逻辑对齐：

4. 可配置项

不传参即用默认值。

4.1 协议档说明

联调建议：先用串口/厂商手册确认帧样例，再选内置档；内置档不匹配时用 template，并按实际帧头尾配置 frameHeader / frameTrailer / frameDelimiter。

4.2 template 示例正则库

protocolProfile: 'template' 时，将下列某一条复制到 templateRegex，templateWeightGroup 取捕获组序号（下列均为 1）。

插件导出 PROTOCOL_TEMPLATE_LIBRARY 与下表一致，可直接按 id 选取：

手写正则示例（与上表等价）：

# CAS/托利多毛重 G/xxx.xxxkg
G[/,\s]*([0-9.+-]+)\s*kg

# 净重 N/xxx.xxxkg
N[/,\s]*([0-9.+-]+)\s*kg

# 行内浮点公斤（可前置 ST/US 等杂讯）
([0-9]+(?:\.[0-9]+)?)\s*kg

# ww/wn 文本重量
w[wn]\s*([0-9.+-]+)\s*kg

亦可从 PROTOCOL_TEMPLATE_LIBRARY 取 regex / weightGroup（id、title 便于业务侧展示或切换）。

示例：

init({
  protocolProfile: 'template',
  templateRegex: 'G[/,\s]*([0-9.+-]+)\\s*kg',
  templateWeightGroup: 1,
  // 行式输出常见以换行切帧：
  frameDelimiter: '\n',
  frameHeader: '',
  frameTrailer: '',
  onWeight(res) { console.log(res.weight) },
})

5. 完整示例

import {
  init,
  startScan,
  connect,
  tare,
  getLastWeight,
  disconnect,
  destroy,
} from '@/uni_modules/breao-bleweight'

init({
  transport: 'ble',
  protocolProfile: 'yaohua_stx',
  continuousCommand: 'RN1',
  weightThrottleMs: 80,
  onWeight(res) {
    console.log('weight', res.weight, res.unit, 'stable=', res.stable)
  },
  onDisconnected() {
    console.log('scale disconnected')
  },
  success() {
    startScan({
      timeout: 8000,
      success(scanRes) {
        const dev = scanRes.devices && scanRes.devices[0]
        if (!dev) return
        connect({
          address: dev.address,
          success() {
            tare({
              success() {
                getLastWeight({
                  success(last) {
                    console.log('last', last.sample)
                    disconnect({ success() { destroy({}) } })
                  },
                })
              },
            })
          },
        })
      },
    })
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于连接电子秤与接收称重数据。

7. 错误码（907）

8. 平台注意

• uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.2.8+ 并重打自定义基座
• Android 默认 transport: 'ble'；老式经典蓝牙秤请设 transport: 'spp'，建议系统先配对
• Android 扫描/连接前插件会申请蓝牙与定位运行时权限；业务仍须在隐私弹窗与系统设置中引导用户开启
• iOS / 微信几乎只能 BLE；请先 startScan 再 connect（iOS 依赖扫描缓存外设）
• 鸿蒙为 BLE GATT 通知读，不支持 spp；支持 getBondedDevices
• 先扫后连：未扫描/未取已配对列表直接 connect 返回 9070006 及中文提示
• 耀华类秤连上后若无数据，插件会按配置发送 continuousCommand（默认 RN1）并重试
• BLE UUID 留空时自动匹配可通知 / 可写特征；特殊机型请在 init 填写厂商 UUID
• template 档须提供能捕获重量的正则，并用 templateWeightGroup 指定组号；示例见 §4.2
• 切换 transport 或彻底释放资源时，请 destroy 后再重新 init

断线与恢复

• 主动 disconnect / destroy 属于有意关闭，不会触发 onDisconnected，也不会自动重连
• 意外断线（GATT 关闭、链路丢失等）会回调 onDisconnected；业务可在此提示用户或自行 connect
• autoReconnectMax > 0（或兼容 autoReconnectOnce: true）时：同一次 init 生命周期内，按次数上限自动用上次成功地址重连，间隔按 autoReconnectBackoffMs 指数退避（如 500、1000、2000…）
• 用尽重连次数后需业务自行 connect，或 destroy 后重新 init
• destroy 后清空 onWeight / onDisconnected，不会再回调
• 自动重连成功后仍会走连接后流程（含 continuousCommand 与无数据重试）
• 不保证弱网/频繁开关蓝牙下的无限重连；本插件不做连接池与多秤会话