更新记录

1.0.0（2026-08-12）

首发正式版。 Android 经典蓝牙 SPP + 局域网 TCP； iOS BLE + 局域网； 鸿蒙局域网； 微信 BLE。 支持 printText/printBytes、对齐/加粗/走纸/切纸； LAN 默认端口 9100； BLE 分片与 UUID、nameHints 可配。 无品牌帧、无 UDP 发现、无条码二维码高阶 API。

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-escposprint 使用说明

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

当前版本：1.0.0

• Android / iOS：蓝牙 + 局域网（默认 TCP 9100）
• 鸿蒙：仅局域网
• 微信小程序：仅 BLE
• 能力：文本/字节打印、对齐加粗、走纸切纸、ESC 组帧辅助
• 不做全协议万能机、品牌官方 SDK 合集、USB 直连

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

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-escposprint，或从插件市场导入后同步。

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  connectBluetooth,
  connectLan,
  disconnect,
  printText,
  printBytes,
  setAlign,
  setBold,
  feed,
  cut,
  getConnectionState,
  buildEscInit,
  buildEscAlign,
  buildEscCut,
} from '@/uni_modules/breao-escposprint'

3. API

3.1 init / destroy

init({
  transport: 'lan', // 或 bluetooth；详见 §4
  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() {} })

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

说明：iOS / 微信请先扫描再连接；参数默认值见 §4。

3.3 局域网连接

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

3.4 打印与便捷指令

printText({ content: 'Hello ESC/POS', success() {}, fail() {} })
printBytes({ data: arrayBuffer, success() {}, fail() {} })
setAlign({ align: 'center', success() {}, fail() {} })
setBold({ bold: true, success() {}, fail() {} })
feed({ lines: 3, success() {}, fail() {} })
cut({ mode: 'partial', success() {}, fail() {} })

3.5 状态与断开

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

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

3.6 协议辅助（同步）

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

4. 可配置项

不传参即用默认值。

4.1 transport 与端能力

5. 完整示例

5.1 局域网

import {
  init,
  connectLan,
  printText,
  setAlign,
  feed,
  cut,
  disconnect,
  destroy,
} from '@/uni_modules/breao-escposprint'

init({
  transport: 'lan',
  success() {
    connectLan({
      host: '192.168.1.100',
      success() {
        setAlign({
          align: 'center',
          success() {
            printText({
              content: 'Store Receipt',
              success() {
                feed({
                  lines: 2,
                  success() {
                    cut({
                      mode: 'partial',
                      success() {
                        disconnect({ success() { destroy({}) } })
                      },
                    })
                  },
                })
              },
            })
          },
        })
      },
      fail(err) {
        console.error(err.errCode, err.errMsg)
      },
    })
  },
})

5.2 蓝牙

import { init, startBluetoothScan, connectBluetooth, printText, 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() {
            printText({ content: '蓝牙小票' })
          },
        })
      },
    })
  },
})

6. 权限

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

7. 错误码（906）

8. 平台注意

• 局域网热敏多数默认端口 9100；若厂商不同请改 lanPort / connectLan.port
• 中文小票常见 GBK；若端侧编码不可用，请业务侧转 GBK 后 printBytes
• 连接后不会自动发送 ESC @；需要时可 printBytes(buildEscInit())
• iOS / 微信 BLE 请先 startBluetoothScan 再 connectBluetooth，以便缓存外设
• Android 12+ 蓝牙扫描通常需要定位权限；请在运行时申请并引导用户开启蓝牙
• BLE UUID 留空时自动匹配可写特征；特殊机型请在 init 填写厂商 UUID
• 切换 transport 或彻底释放资源时，请 destroy 后再重新 init