更新记录

1.0.0（2026-08-13）

首版：轻量 CPCL 面单打印。Android 支持 BLE、经典蓝牙 SPP 与局域网 TCP；iOS 支持 BLE 与局域网；鸿蒙支持局域网；微信小程序支持 BLE。提供 printJob 任务打印（文本、条码、二维码、线条、方框、EG 单色位图）与 sendRaw 原始字节发送；支持 dryRun 预览指令字节。默认 DPI 203，面单尺寸毫米、元素坐标点（dot）。

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-cpclprint 使用说明

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

当前版本：1.0.0

• Android：BLE、经典蓝牙 SPP、局域网 TCP（默认 9100）
• iOS：BLE + 局域网
• 鸿蒙：仅局域网
• 微信小程序：仅 BLE
• 能力：printJob 任务打印（文本/条码/二维码/线/框/单色位图 EG）、sendRaw 原始字节、dryRun 预览
• 不做 ZPL/TSPL 同包、不做品牌官方 SDK 全家桶、不做固件升级、不做云模板

建议调用顺序：init → 扫描/连接 → printJob 或 sendRaw → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 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）、微信小程序
• 不支持：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,
  getConnectionState,
  buildPrintJobBytes,
  mmToDots,
  dpiToRes,
  buildCpclSession,
  buildCpclPageWidth,
  buildCpclPrint,
} from '@/uni_modules/breao-cpclprint'

3. API

3.1 init / destroy

init({
  transport: 'lan', // ble | spp(仅 Android) | lan
  dpi: 203,
  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) {},
})

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 时不发送，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() {} })

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

3.5 状态与断开

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

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

3.6 协议辅助（同步）

4. 可配置项

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. 平台注意

• 局域网面单机多数默认端口 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
• iOS / 微信 BLE 建议先扫描再连接，以便缓存外设与可写特征
• Android 部分老款机仅支持 SPP，请 transport: 'spp'；BLE 机用 ble
• dryRun: true 可用于联调指令，无需连接打印机
• 不同固件对字体编号、条码类型关键字可能有差异，可用 sendRaw 兜底