更新记录

1.2.6（2026-09-07）

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

1.2.5（2026-09-07）

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

1.2.4（2026-09-06）

• 修复 Android 运行时 ClassCastException：成功回调结果改为 UTSJSONObject 别名，避免强转为独立 SuccessResult 类型
• 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-hprtprint 使用说明

汉印（HPRT）便携热敏打印插件，适用于 App 端标签 / 票据机场景。

当前版本：1.2.6

• Android：CPCL + ESC；蓝牙、WiFi、UDP 局域网发现
• iOS：CPCL；蓝牙、WiFi、LAN 发现
• 能力：printText / printBytes / printBarcode / printQr / printImage / getPrinterStatus；driver: auto 按机型选 CPCL 或 ESC；连接态含 busy
• 不做 USB、鸿蒙 / 微信、其它厂商打印机

建议调用顺序：init → 扫描 → 连接 → printText / printBarcode / printQr / printImage / printBytes / getPrinterStatus → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。扫描/连接/打印互斥时 getConnectionState 可能返回 busy。

1. 环境要求

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

2. 安装与引入

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

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  connectBluetooth,
  startWifiScan,
  stopWifiScan,
  connectWifi,
  disconnect,
  printText,
  printBytes,
  printBarcode,
  printQr,
  printImage,
  getPrinterStatus,
  getConnectionState,
} from '@/uni_modules/breao-hprtprint'

3. API

3.1 init / destroy

init({
  driver: 'cpcl', // auto | cpcl | esc（esc 仅 Android）；全量见 §4
  transport: 'bluetooth', // bluetooth | wifi
  modelHint: 'HM-A300',
  debug: false,
  onDisconnected(res) {
    console.log(res.address)
  },
  success() {},
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

destroy({ success() {}, fail(err) {} })

driver: 'auto' 且 modelHint 含 E200 / E300 / TP80 等走 ESC，否则默认 CPCL；transport: 'wifi' 且 auto 时默认 ESC。

3.2 蓝牙扫描与连接

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

stopBluetoothScan({ success() {}, fail() {} })

connectBluetooth({
  address: '…', // Android=MAC（建议大写）；iOS=扫描结果 address
  timeout: 15000,
  success() {},
  fail(err) {},
})

3.3 WiFi / 局域网

startWifiScan({
  timeout: 5000,
  success(res) {
    // res.devices: [{ ip, sn?, mac?, name? }]
  },
  fail(err) {},
})

stopWifiScan({ success() {}, fail() {} })

connectWifi({
  ip: '192.168.1.100',
  timeout: 15000,
  success() {},
  fail(err) {},
})

Android CPCL 下 startWifiScan 返回 9020010；可手填 IP 直接 connectWifi。端能力见 §4.1。

3.4 打印与状态

printText({
  content: 'Hello HPRT\n第二行',
  pageWidth: 384,
  success() {},
  fail(err) {},
})

printBytes({ data: arrayBuffer })

getConnectionState({
  success(st) {
    // st.state（含 busy）/ st.busy / transport / driver / address
  },
})

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

3.x printBarcode / printQr / printImage / getPrinterStatus

printBarcode({
  content: '123456789012',
  type: 'CODE128', // CODE128 | CODE39 | EAN13 | EAN8 | UPCA | UPCE | CODABAR | CODE93
  height: 60,
  width: 2,
  success() {},
  fail(err) {},
})

printQr({
  content: 'https://example.com',
  unitWidth: 6,
  errorLevel: 'M',
  success() {},
  fail(err) {},
})

printImage({
  // path 与 base64 二选一，优先 path
  path: '/path/to/label.png',
  // base64: '...',
  success() {},
  fail(err) {},
})

getPrinterStatus({
  success(res) {
    // res.online / res.driver / res.transport / res.address / res.rawStatus / res.busy
  },
  fail(err) {},
})

getPrinterStatus success 字段：

getPrinterStatus 以连接态为主返回 online；Android 会尝试读取官方 SDK 状态码到 rawStatus，无法回读时为 -1。

4. 可配置项

| content | printBarcode / printQr | 必填 | 条码/二维码内容 | | type | printBarcode | CODE128 | 条码类型 | | height | printBarcode | 60 | 条码高度（dot） | | width | printBarcode | 2 | 窄条/模块宽 | | showText | printBarcode | true | 是否打印可读文字（CPCL）；ESC 忽略 | | ratio | printBarcode | 1 | 宽窄比（CPCL）；ESC 忽略 | | unitWidth | printQr | 6 | QR 模块宽度 1～32 | | model | printQr | 2 | QR 型号 1 或 2（CPCL） | | errorLevel | printQr | M | QR 纠错 L/M/Q/H | | path / base64 | printImage | 二选一 | 本地路径优先；base64 可含 dataURL 前缀 | | x / y | printBarcode / printQr / printImage | 0 | 起点（dot） | | pageWidth | printBarcode / printQr / printImage | 384 | CPCL 打印区域宽度 |

不传参即用默认值。

4.1 端能力摘要

5. 完整示例

5.1 蓝牙 CPCL

import {
  init,
  startBluetoothScan,
  connectBluetooth,
  printText,
  disconnect,
  destroy,
} from '@/uni_modules/breao-hprtprint'

init({
  driver: 'cpcl',
  transport: 'bluetooth',
  modelHint: 'HM-A300',
  success() {
    startBluetoothScan({
      timeout: 10000,
      success(res) {
        const d = res.devices && res.devices[0]
        if (!d) return
        connectBluetooth({
          address: d.address,
          success() {
            printText({
              content: 'Hello HPRT',
              success() {
                disconnect({ success() { destroy({}) } })
              },
            })
          },
        })
      },
    })
  },
})

5.2 WiFi ESC 票据机

import {
  init,
  startWifiScan,
  connectWifi,
  printText,
  disconnect,
  destroy,
} from '@/uni_modules/breao-hprtprint'

init({
  driver: 'esc',
  transport: 'wifi',
  modelHint: 'HM-E200',
  success() {
    startWifiScan({
      timeout: 5000,
      success(res) {
        const d = res.devices && res.devices[0]
        const ip = d ? d.ip : '192.168.1.100'
        connectWifi({
          ip,
          success() {
            printText({
              content: 'WiFi Ticket',
              success() {
                disconnect({ success() { destroy({}) } })
              },
            })
          },
        })
      },
    })
  },
})

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于连接汉印打印机并发送打印数据。

7. 错误码（902）

8. 平台注意

• uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.2.6+ 并重打自定义基座
• iOS 须先 startBluetoothScan 再 connectBluetooth；无 ESC 驱动
• Android ESC 与 CPCL 可同包共存；票据机常用 HM-E200 / E300、TP801 / TP805
• WiFi 时手机与打印机须同一局域网；Android CPCL 无 UDP 发现，可手填 IP 直接 connectWifi
• Android ESC 的 startWifiScan 走 UDP；iOS CPCL 走 LAN 扫描
• CPCL 面单机常用 HM-A300；切换 driver / transport 后建议 destroy 再 init
• printBytes 在 HBuilderX 4.51 以下可能编译异常，请升级 IDE
• getConnectionState 的 state 在扫描/连接/打印互斥进行时可返回 busy；同时 busy: true