更新记录

1.1.8（2026-09-07）

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

1.1.7（2026-09-07）

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

1.1.6（2026-09-06）

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

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-xprinter 使用说明

芯烨 XPrinter 票据打印插件，适用于收银、餐饮小票等芯烨热敏机场景。

当前版本：1.1.8

• Android：蓝牙经典 SPP + 局域网 TCP + USB Host
• iOS：BLE/BT + 局域网 TCP
• 鸿蒙：官方 SDK（蓝牙 / 局域网 / USB，har 已内置；uni-app 与 uni-app x）
• 能力：文本/多列、对齐加粗字号、条码/二维码/位图、切纸/钱箱/蜂鸣、状态查询、纸宽 58/72/80、原始字节透传、短打印队列
• 不做微信小程序端（请改用 breao-escposprint）、芯烨云开放 API、全量 TSPL 标签排版引擎

建议调用顺序：init → connectBluetooth / connectLan / connectUsb → 打印指令 → 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-Android / App-iOS / App-鸿蒙）
• 支持：App-Android、App-iOS、App-鸿蒙（uni-app 与 uni-app x）
• 不支持：H5、微信及其它小程序
• 微信小程序请使用 breao-escposprint（轻量 ESC 透传）；本插件依赖芯烨官方 SDK（jar / xcframework / 鸿蒙 har），官方包不覆盖微信端，故微信标为不支持
• Android 最低 API：21；iOS 最低 12；鸿蒙最低 API：12
• App 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包
• 授权绑定唯一 appid + 包名

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-xprinter，或从插件市场导入后同步。官方 SDK 二进制已内置，无需再手动下载 jar / xcframework，也无需执行 ohpm install @xpsdk/printersdk。

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  getBondedDevices,
  connectBluetooth,
  connectLan,
  connectUsb,
  disconnect,
  getConnectionState,
  printText,
  printColumns,
  printBytes,
  sendRaw,
  setAlign,
  setBold,
  setFontSize,
  feed,
  printDivider,
  printBarcode,
  printQrcode,
  printImage,
  cutPaper,
  openCashBox,
  beep,
  getPrinterStatus,
  // 协议辅助（可选）
  buildEscInit,
  buildEscAlign,
  buildEscBold,
  buildEscFontSize,
  buildEscFeed,
  buildEscDivider,
  buildEscCut,
  buildEscTextAscii,
  buildEscColumnsAscii,
  buildEscBarcode,
  buildEscQrcode,
  buildEscOpenCashBox,
  buildEscBeep,
  buildEscStatusQuery,
  concatEscBytes,
  DEFAULT_LAN_PORT,
  DEFAULT_PAPER_WIDTH_MM,
} from '@/uni_modules/breao-xprinter'

3. API

3.1 init / destroy

init({
  transport: 'lan',
  paperWidthMm: 80,
  encoding: 'gbk',
  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) {},
})

getBondedDevices({ success(res) {}, fail(err) {} }) // Android 已配对列表

connectBluetooth({ address: 'XX:XX:XX:XX:XX:XX', success() {}, fail(err) {} })
connectLan({ host: '192.168.1.100', success() {}, fail(err) {} })
connectUsb({ success() {}, fail(err) {} }) // 须 init({ transport: 'usb' })

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

说明：iOS 请先扫描再连接；鸿蒙蓝牙传系统蓝牙设备 id；参数默认值见 §4。

3.3 打印与排版

printText({ content: 'Hello XPrinter', success() {}, fail() {} })
printColumns({ columns: ['品名', '数量', '金额'], widths: [2, 1, 1], success() {}, fail() {} })
setAlign({ align: 'center', success() {}, fail() {} })
setBold({ bold: true, success() {}, fail() {} })
setFontSize({ width: 2, height: 2, success() {}, fail() {} })
printBarcode({ content: '123456789012', type: 'CODE128', success() {}, fail() {} })
printQrcode({ content: 'https://example.com/order/1', success() {}, fail() {} })
printImage({ base64: '...', align: 'center', success() {}, fail() {} })
cutPaper({ mode: 'partial', success() {}, fail() {} })
openCashBox({ pin: 0, success() {}, fail() {} })
beep({ times: 1, duration: 3, success() {}, fail() {} })
feed({ lines: 3, success() {}, fail() {} })
printDivider({ char: '-', success() {}, fail() {} })
printBytes({ data: arrayBuffer, success() {}, fail() {} })
sendRaw({ data: arrayBuffer, success() {}, fail() {} }) // 不经队列直接发送原始字节

3.4 状态查询

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

getPrinterStatus({
  success(res) {
    // res.online / paperWidthMm / transport / rawStatus（无回读时为 -1）
  },
  fail(err) {},
})

3.6 协议辅助（同步）

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

4. 可配置项

不传参即用默认值。

4.1 transport 与端能力

鸿蒙不支持 getBondedDevices（返回 9080010）；请使用系统已配对蓝牙设备的 deviceId 作为 connectBluetooth.address，或通过 startBluetoothScan 获取设备 id。

5. 完整示例

import {
  init,
  connectLan,
  setAlign,
  printText,
  printQrcode,
  cutPaper,
  destroy,
} from '@/uni_modules/breao-xprinter'

init({
  transport: 'lan',
  paperWidthMm: 80,
  encoding: 'gbk',
  success() {
    connectLan({
      host: '192.168.1.100',
      port: 9100,
      success() {
        setAlign({ align: 'center' })
        printText({ content: '芯烨小票' })
        printQrcode({ content: 'https://example.com/order/1' })
        cutPaper({
          mode: 'partial',
          success() {
            destroy({})
          },
        })
      },
      fail(err) {
        console.error(err.errCode, err.errMsg)
      },
    })
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

6. 权限

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

7. 错误码（908）

8. 平台注意

• uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.1.8+ 并重打自定义基座
• Android 蓝牙为经典 SPP；可用 nameHints 覆盖默认 XP- / XPrinter / 芯烨 等过滤
• iOS 蓝牙为 BLE：须先 startBluetoothScan，再用扫描结果中的 address 连接
• 局域网默认端口 9100；机型不同可用 connectLan.port 覆盖
• USB：Android 与鸿蒙支持；请先 init({ transport: 'usb' }) 再 connectUsb
• 鸿蒙蓝牙 address 为系统蓝牙设备 id；局域网 connectLan 会按 host,port 交给官方 SDK
• 微信小程序：官方 SDK 无微信包，本插件不提供微信 BLE；若仅需 ESC 字节透传打印，请使用 breao-escposprint
• 连续打印走短队列（上限 32）；队列满返回 9080002；disconnect / destroy / 再次 init 会清空队列
• 协议辅助函数见 §3.6；拼装 ESC 字节后可用 printBytes / sendRaw
• printImage 推荐传入已光栅化的 ESC 字节 base64；仅传 path 时请先在业务侧读文件再 printBytes
• getPrinterStatus 以连接态为主；部分机型无状态回读时 rawStatus 为 -1
• 鸿蒙 getBondedDevices 不可用（9080010）；蓝牙连接请传系统 deviceId，勿依赖已配对列表接口
• 切换 transport 或彻底释放资源时，请 destroy 后再重新 init