更新记录

1.3.8（2026-09-07）

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

1.3.7（2026-09-07）

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

1.3.6（2026-09-06）

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

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-escposprint 使用说明

轻量 ESC/POS 热敏打印插件，适用于收银、餐饮小票等通用热敏机场景。

当前版本：1.3.8

• Android：默认经典蓝牙 SPP；init 填写 BLE UUID 时走 GATT BLE；局域网 TCP
• iOS：BLE + 局域网
• 鸿蒙：BLE + 局域网（uni-app / uni-app x）
• 微信小程序：仅 BLE
• 能力：文本/多列、对齐加粗字号、分隔线、条码/二维码/位图、切纸/钱箱/蜂鸣、短打印队列、状态查询、纸宽 58/72/80、原始字节透传
• 不做 H5、USB、品牌官方 SDK 合集、PNG 自动光栅

建议调用顺序：init → 扫描/连接 → 打印指令 → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 init 会销毁上一实例。连续 print* 会进入短队列串行发送；队列执行中 getConnectionState 可能返回 busy。

1. 环境要求

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

2. 安装与引入

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

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  getBondedDevices,
  connectBluetooth,
  connectLan,
  disconnect,
  printText,
  printColumns,
  printBytes,
  sendRaw,
  printBarcode,
  printQrcode,
  printImage,
  setAlign,
  setBold,
  setFontSize,
  feed,
  printDivider,
  cut,
  cutPaper,
  openCashBox,
  beep,
  getPrinterStatus,
  getConnectionState,
  buildEscInit,
  buildEscAlign,
  buildEscCut,
  buildEscFontSize,
  buildEscDivider,
  buildEscOpenCashBox,
  buildEscBeep,
  buildEscColumnsAscii,
  buildEscBarcode,
  buildEscQrcode,
} from '@/uni_modules/breao-escposprint'

3. API

3.1 init / destroy

init({
  transport: 'lan', // 或 bluetooth；详见 §4
  paperWidthMm: 80,
  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,
  success(res) {
    // res.devices: [{ name, address, rssi?, bonded? }]
  },
  fail(err) {},
})

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

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

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

说明：请先扫描再连接（未扫描直接 connect 会返回中文错误）；参数默认值见 §4。

3.3 局域网连接

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

3.4 打印与便捷指令

printText({ content: 'Hello ESC/POS', success() {}, fail() {} })
printColumns({ columns: ['品名', '数量', '金额'], widths: [2, 1, 1], success() {}, fail() {} })
printBytes({ data: arrayBuffer, success() {}, fail() {} })
sendRaw({ data: arrayBuffer, success() {}, fail() {} }) // 等同 printBytes
printBarcode({
  content: '123456789012',
  type: 'CODE128',
  height: 60,
  width: 2,
  hri: 'below',
  success() {},
  fail() {},
})
printQrcode({
  content: 'https://example.com',
  moduleSize: 6,
  errorLevel: 'M',
  success() {},
  fail() {},
})
// base64 / path 均须已是 ESC 光栅或原始打印字节；不做 PNG→光栅
printImage({ base64: escRasterBase64, align: 'center', success() {}, fail() {} })
printImage({ path: '/path/to/esc.bin', success() {}, fail() {} }) // 微信请改传 base64
setAlign({ align: 'center', success() {}, fail() {} })
setBold({ bold: true, success() {}, fail() {} })
setFontSize({ width: 2, height: 2, success() {}, fail() {} })
printDivider({ char: '-', success() {}, fail() {} })
feed({ lines: 3, success() {}, fail() {} })
cut({ mode: 'partial', success() {}, fail() {} })
cutPaper({ mode: 'partial', success() {}, fail() {} }) // 等同 cut
openCashBox({ pin: 0, success() {}, fail() {} })
beep({ times: 1, duration: 3, success() {}, fail() {} })

3.5 状态与断开

getPrinterStatus({
  success(res) {
    // res.online；res.rawStatus 多数机型为 -1（无可靠 DLE EOT 回读）
  },
  fail(err) {},
})

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

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

3.6 协议辅助（同步）

可在业务侧自组报文后 printBytes / sendRaw：

4. 可配置项

不传参即用默认值。

4.1 transport 与端能力

5. 完整示例

5.1 局域网

import {
  init,
  connectLan,
  printText,
  setFontSize,
  printDivider,
  openCashBox,
  cutPaper,
  disconnect,
  destroy,
} from '@/uni_modules/breao-escposprint'

init({
  transport: 'lan',
  paperWidthMm: 80,
  success() {
    connectLan({
      host: '192.168.1.100',
      success() {
        setFontSize({
          width: 2,
          height: 2,
          success() {
            printText({
              content: 'Store Receipt',
              success() {
                printDivider({
                  success() {
                    openCashBox({
                      success() {
                        cutPaper({
                          mode: 'partial',
                          success() {
                            disconnect({ success() { destroy({}) } })
                          },
                        })
                      },
                    })
                  },
                })
              },
            })
          },
        })
      },
      fail(err) {
        console.error(err.errCode, err.errMsg)
      },
    })
  },
})

5.2 蓝牙

import { init, startBluetoothScan, connectBluetooth, printColumns, destroy } from '@/uni_modules/breao-escposprint'

init({
  transport: 'bluetooth',
  success() {
    startBluetoothScan({
      success(res) {
        const dev = res.devices && res.devices[0]
        if (!dev) return
        connectBluetooth({
          address: dev.address,
          success() {
            printColumns({ columns: ['品名', '数量', '金额'], widths: [2, 1, 1] })
          },
        })
      },
    })
  },
})

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于连接 ESC/POS 热敏打印机与发送打印数据。插件会申请相关权限，业务仍须引导用户开启蓝牙/网络。

7. 错误码（906）

8. 平台注意

• uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.3.8+ 并重打自定义基座
• 局域网热敏多数默认端口 9100；若厂商不同请改 lanPort / connectLan.port
• 中文小票常见 GBK；若端侧编码不可用，请业务侧转 GBK 后 printBytes
• 连接后不会自动发送 ESC @；需要时可 printBytes(buildEscInit())
• 请先 startBluetoothScan 再 connectBluetooth；未扫描直接连接会返回稳定中文错误
• Android 默认经典 SPP；BLE 打印机请在 init 填写 bleServiceUuid / bleCharacteristicUuid
• Android 12+ 蓝牙扫描通常需要定位权限；请在运行时申请并引导用户开启蓝牙
• BLE UUID 留空时（iOS / 鸿蒙 / 微信 / Android BLE 模式）自动匹配可写特征；特殊机型请填写厂商 UUID
• printImage.path 按原始字节读取，须已是 ESC 光栅数据；不做 PNG 自动光栅；微信请业务侧读文件后传 base64
• 切换 transport 或彻底释放资源时，请 destroy 后再重新 init
• 短打印队列深度为 32；printText / printBytes / printBarcode 等 print* 串行入队
• 队列已满时 fail 返回 9060002，errMsg 为「打印队列已满，请稍后重试」
• init（含再次 init）、disconnect、destroy 会清空尚未执行的队列任务