更新记录

1.3.7（2026-09-07）

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

1.3.6（2026-09-06）

• 修复协议 EG/状态解析/Hex：ByteArray.size 与下标 Number.from
• 修复协议 concat：ByteArray.size 先 Number.from 再拼接
• 修复 App 端成功回调与驱动稳定性：去掉 undefined、可变属性强制解包改为局部拷贝；iOS BLE 状态/特性用 Number.from
• 修复 Android BLE 分片打印：ByteArray.size 先 Number.from 再与 offset 比较
• 修复 Android 运行时 ClassCastException：成功回调结果改为 UTSJSONObject 别名，避免强转为独立 SuccessResult 类型
• 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

1.3.4（2026-09-04）

• 修复 Android 云打包：可选 number 先 Number.from 再比较返回，避免 compareTo / expected Number actual Any
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 不传参行为与上一版兼容
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-cpclprint 使用说明

轻量 CPCL 面单打印插件，适用于快递面单、仓储物流等 CPCL 热敏打印机。

当前版本：1.3.7

• Android：BLE、经典蓝牙 SPP、局域网 TCP（默认 9100）
• iOS：BLE + 局域网
• 鸿蒙：BLE + 局域网
• 微信小程序：仅 BLE
• 能力：printJob / sendRaw / getPrinterStatus / getBondedDevices；encoding（GBK/UTF-8）；短打印队列与 busy；dryRun 免 init
• 不做 ZPL/TSPL 同包、不做品牌官方 SDK 全家桶、不做固件升级、不做云模板

建议调用顺序：init → 扫描/连接 → printJob / sendRaw / getPrinterStatus → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 init 会销毁上一实例。连续 printJob/sendRaw 进入短队列；队列执行中 getConnectionState 可能返回 busy。dryRun: true 无需 init/连接。

坐标说明： 面单 widthMm / heightMm 为毫米；元素 x / y 等为点（dot）。换算：dots = Math.round(mm × dpi ÷ 25.4)，默认 dpi 为 203（会话头分辨率 200）；亦可选 300。image.width 为 EG 字节宽，image.height 为行数。

1. 环境要求

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

2. 安装与引入

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

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  connectBluetooth,
  connectLan,
  disconnect,
  printJob,
  sendRaw,
  getPrinterStatus,
  getBondedDevices,
  getConnectionState,
  buildPrintJobBytes,
  mmToDots,
  dpiToRes,
  buildCpclSession,
  buildCpclPageWidth,
  buildCpclText,
  buildCpclBarcode,
  buildCpclQrcode,
  buildCpclLine,
  buildCpclBox,
  buildCpclEg,
  buildCpclForm,
  buildCpclPrint,
  buildCpclStatusQuery,
  parseCpclStatusResponse,
  normalizeEncoding,
} from '@/uni_modules/breao-cpclprint'

3. API

3.1 init / destroy

init({
  transport: 'lan', // ble | spp(仅 Android) | lan
  dpi: 203,
  encoding: 'gbk', // gbk | utf-8
  debug: false,
  onDisconnected(res) {
    console.log('disconnected', res)
  },
  success() {},
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

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

3.2 蓝牙扫描与连接

startBluetoothScan({
  timeout: 10000,
  nameHints: ['CPCL', 'HM-', 'Label'],
  success(res) {
    // res.devices: [{ name, address, rssi?, bonded? }]
  },
  fail(err) {},
})

getBondedDevices({ success(res) {}, fail(err) {} }) // Android / 鸿蒙已配对；其它端返回不支持

connectBluetooth({
  address: 'XX:XX:XX:XX:XX:XX',
  success() {},
  fail(err) {},
})

3.3 局域网连接

connectLan({
  host: '192.168.1.100',
  port: 9100,
  success() {},
  fail(err) {},
})

3.4 printJob / sendRaw

printJob({
  widthMm: 76,
  heightMm: 130,
  dpi: 203,
  copies: 1,
  dryRun: false, // true：无需 init/连接，success 返回 length / hex / bytes
  elements: [
    { type: 'text', x: 30, y: 40, content: '收件人', font: '4', xMul: 0, rotation: 0 },
    { type: 'barcode', x: 30, y: 100, content: 'SF1234567890', height: 80, codeType: '128' },
    { type: 'qrcode', x: 400, y: 40, content: 'https://example.com', cellWidth: 6 },
    { type: 'box', x: 20, y: 20, x2: 560, y2: 900, thickness: 2 },
    { type: 'line', x: 20, y: 200, x2: 560, y2: 200, thickness: 2 },
    { type: 'image', x: 0, y: 0, width: 48, height: 40, base64: '<单色行数据 base64>' },
  ],
  success(res) {},
  fail(err) {},
})

sendRaw({ data: arrayBuffer, dryRun: false, success() {}, fail() {} })
// dryRun: true 时 success 同样返回 length（字节数）、hex（十六进制预览）、bytes（ArrayBuffer）

详见 §4 元素字段；image.path 在 App 端可读本地文件时自动转 base64。

3.5 状态与断开

getPrinterStatus({
  success(res) {
    // res.online: 是否已连接
    // res.rawStatus: 能回读解析则为值，否则 -1；探测仍下发
    // res.transport / res.address
  },
  fail(err) {},
})

getConnectionState({
  success(res) {
    // res.state: disconnected | connecting | connected | busy
    // res.busy
  },
  fail(err) {},
})

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

getPrinterStatus 以连接态为主：online === (state === 'connected')。已连接时会下发探测指令 ! U1 getvar "power.percent"\r\n（Zebra/兼容常见电量查询）。多数廉价 CPCL 机无可靠回读或忽略该指令；本插件不解析回包，故 rawStatus 恒为 -1。边界：仅保证「已连接则尝试探测」；电量/纸仓等细粒度状态请用 sendRaw 按机型手册自行查询。

3.6 协议辅助（同步）

4. 可配置项

不传参即用默认值。Android 经典 SPP 忽略全部 BLE 间隔/UUID/分片参数。

4.1 transport 与端能力

4.2 printJob 元素字段（坐标均为 dot）

5. 完整示例

5.1 局域网打印面单

import { init, connectLan, printJob, disconnect, destroy } from '@/uni_modules/breao-cpclprint'

init({
  transport: 'lan',
  success() {
    connectLan({
      host: '192.168.1.100',
      success() {
        printJob({
          widthMm: 76,
          heightMm: 130,
          elements: [
            { type: 'text', x: 30, y: 40, content: '收件人：张三' },
            { type: 'barcode', x: 30, y: 100, content: 'SF1234567890', height: 70 },
          ],
          success() {
            disconnect({ success() { destroy({}) } })
          },
        })
      },
    })
  },
})

5.2 Android 经典蓝牙 SPP

import { init, startBluetoothScan, connectBluetooth, printJob } from '@/uni_modules/breao-cpclprint'

init({
  transport: 'spp',
  success() {
    startBluetoothScan({
      success(res) {
        const dev = res.devices && res.devices[0]
        if (!dev) return
        connectBluetooth({
          address: dev.address,
          success() {
            printJob({
              widthMm: 76,
              heightMm: 130,
              dryRun: true,
              elements: [{ type: 'text', x: 30, y: 40, content: 'Preview' }],
              success(res) {
                console.log(res.hex)
              },
            })
          },
        })
      },
    })
  },
})

6. 权限

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

7. 错误码（912）

8. 平台注意

• uni-app x（.uvue）：1.3.7 起可直接传对象字面量调用 API，无需 as XxxOption；须使用 1.3.7+ 并重打自定义基座
• 局域网面单机多数默认端口 9100；厂商不同请改 lanPort / connectLan.port
• 毫米与 dot 勿混用：widthMm 等为毫米；elements[].x/y 等为 dot，可用 mmToDots 换算
• image 为 CPCL EG 单色行数据 base64；完整 PNG 解码需业务侧预处理；width 为字节宽、height 为行数
• 文本 rotation 为 90/180/270 时分别生成 T90/T180/T270
• 请先扫描再连接（未扫描直接 connect 会返回中文错误）；iOS 须用扫描返回的 UUID
• Android 部分老款机仅支持 SPP，请 transport: 'spp'；BLE 机用 ble
• getPrinterStatus 的 online 即连接态；探测指令为 U1 getvar，廉价机可能无响应；细粒度状态请 sendRaw
• dryRun: true 无需 init/连接即可预览 length/hex/bytes
• 元素校验：越界坐标、缺 x2/y2、条码高度等会直接 fail，少打废纸
• 不同固件对字体编号、条码类型关键字可能有差异，可用 sendRaw 兜底
• 短打印队列深度为 32；printJob / sendRaw 串行入队
• 队列已满时 fail 返回 9120002，errMsg 为「打印队列已满，请稍后重试」
• init（含再次 init）、disconnect、destroy 会清空尚未执行的队列任务