更新记录

1.0.0（2026-08-13）

• 首发：芯烨 XPrinter 票据打印 UTS API
• Android：蓝牙经典 SPP、局域网 TCP、USB Host；内置 printer-lib 3.2.0
• iOS：BLE/BT、局域网 TCP；内置 PrinterSDK v2.3.0
• 鸿蒙：官方 printersdk 1.0.6（蓝牙/LAN/USB）已打包，无需另行安装
• 能力：文本/多列、对齐加粗字号、走纸分隔线、条码、二维码、位图透传、切纸、开钱箱、蜂鸣、状态查询、纸宽 58/72/80、透传 sendRaw
• 微信小程序本期不支持

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-xprinter 使用说明

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

当前版本：1.0.0

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

建议调用顺序：init → connectBluetooth / connectLan / connectUsb → 打印指令 → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 init 会销毁上一实例。

1. 环境要求

• HBuilderX 4.11 及以上
• uni-app Vue3（App-vue / App-nvue）或 uni-app x（App-Android / App-iOS；uni-app x 下鸿蒙为不支持）
• 支持：App-Android、App-iOS、App-鸿蒙（仅 uni-app）
• 不支持：H5、微信及其它小程序
• 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,
} 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() {} })
printBytes({ data: arrayBuffer, success() {}, fail() {} })

3.4 状态查询

getConnectionState({
  success(res) {
    // res.state / res.address / res.transport / res.paperWidthMm
  },
  fail(err) {},
})

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

4. 可配置项

不传参即用默认值。

4.1 transport 与端能力

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

• Android 蓝牙为经典 SPP；可用 nameHints 覆盖默认 XP- / XPrinter / 芯烨 等过滤
• iOS 蓝牙为 BLE：须先 startBluetoothScan，再用扫描结果中的 address 连接
• 局域网默认端口 9100；机型不同可用 connectLan.port 覆盖
• USB：Android 与鸿蒙支持；请先 init({ transport: 'usb' }) 再 connectUsb
• 鸿蒙蓝牙 address 为系统蓝牙设备 id；局域网 connectLan 会按 host,port 交给官方 SDK
• printImage 推荐传入已光栅化的 ESC 字节 base64；仅传 path 时请先在业务侧读文件再 printBytes
• getPrinterStatus 以连接态为主；部分机型无状态回读时 rawStatus 为 -1
• 切换 transport 或彻底释放资源时，请 destroy 后再重新 init