更新记录

1.0.0（2026-08-13）

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

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-tsplprint 使用说明

轻量 TSPL/TSC 标签打印插件，适用于仓储、零售价签、物流面单等 TSC 类桌面标签机。

当前版本：1.0.0

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

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

坐标说明： 标签 widthMm / heightMm / gapMm 为毫米；元素 x / y / width / height 等为点（dot）。换算：dots = Math.round(mm × dpi ÷ 25.4)，默认 dpi 为 203（常见 TSC 机）；亦可选 300。

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

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  connectBluetooth,
  connectLan,
  disconnect,
  printJob,
  sendRaw,
  getConnectionState,
  buildPrintJobBytes,
  mmToDots,
  buildTsplSize,
  buildTsplCls,
  buildTsplPrint,
} from '@/uni_modules/breao-tsplprint'

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: ['TSC', '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: 40,
  heightMm: 30,
  gapMm: 2,
  density: 8,
  speed: 4,
  dpi: 203,
  copies: 1,
  dryRun: false, // true 时不发送，success 返回 length / hex / bytes
  elements: [
    { type: 'text', x: 10, y: 10, content: 'Hello', font: '3', rotation: 0 },
    { type: 'barcode', x: 10, y: 60, content: '123456', height: 80, codeType: '128' },
    { type: 'qrcode', x: 200, y: 10, content: 'https://example.com', cellWidth: 4 },
    { type: 'box', x: 5, y: 5, x2: 300, y2: 200, thickness: 2 },
    { type: 'line', x: 10, y: 150, x2: 300, y2: 150 },
    { type: 'image', x: 0, y: 0, width: 320, 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-tsplprint'

init({
  transport: 'lan',
  success() {
    connectLan({
      host: '192.168.1.100',
      success() {
        printJob({
          widthMm: 40,
          heightMm: 30,
          elements: [
            { type: 'text', x: 20, y: 20, content: 'SKU-001' },
            { type: 'barcode', x: 20, y: 60, content: '6901234567890', height: 70 },
          ],
          success() {
            disconnect({ success() { destroy({}) } })
          },
        })
      },
    })
  },
})

5.2 Android 经典蓝牙 SPP

import { init, startBluetoothScan, connectBluetooth, printJob } from '@/uni_modules/breao-tsplprint'

init({
  transport: 'spp',
  success() {
    startBluetoothScan({
      success(res) {
        const dev = res.devices && res.devices[0]
        if (!dev) return
        connectBluetooth({
          address: dev.address,
          success() {
            printJob({
              widthMm: 40,
              heightMm: 30,
              dryRun: true,
              elements: [{ type: 'text', x: 10, y: 10, content: 'Preview' }],
              success(res) {
                console.log(res.hex)
              },
            })
          },
        })
      },
    })
  },
})

6. 权限

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

7. 错误码（911）

8. 平台注意

• 局域网标签机多数默认端口 9100；厂商不同请改 lanPort / connectLan.port
• 毫米与 dot 勿混用：widthMm 等为毫米；elements[].x/y 等为 dot，可用 mmToDots 换算
• image 位图为单色行数据 base64；完整 PNG 解码需业务侧预处理；width 为 dot 宽度、height 为行数
• iOS / 微信 BLE 建议先扫描再连接，以便缓存外设与可写特征
• Android 部分老款机仅支持 SPP，请 transport: 'spp'；BLE 机用 ble
• dryRun: true 可用于联调指令，无需连接打印机