更新记录

1.0.0(2026-11-17)

  • 微信小程序蓝牙打印 UTS 插件首发
  • 支持 ESC/POS 小票打印与 TSPL / CPCL / ZPL 标签打印
  • 支持蓝牙扫描、连接、断开、状态与发送进度监听
  • 支持 Android MTU 协商与分包调整
  • 图片打印:ESC/POS、TSPL 位图,CPCL CG 二进制,ZPL ^GFB 二进制

平台兼容性

uni-app(4.76)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ - - - - - - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
√ - - - - - - - - - - -

uni-app x(4.76)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - - - - √

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × √ √

xl-miniprint

微信小程序蓝牙打印 UTS 插件,支持 ESC/POS 小票、TSPL / CPCL / ZPL 标签打印,内置 GB18030 中文编码。

功能

  • 蓝牙扫描、连接、断开、状态监听
  • 分包发送、发送进度、打印机回传数据监听
  • ESC/POS:文字、对齐、字号、条码、二维码、图片、切纸等
  • TSPL / CPCL / ZPL:尺寸、文字、线条、方框、条码、二维码、图片等
  • 中文直接传入,无需手动转码
  • Android 支持 MTU 协商与自动分包

平台

仅微信小程序,基于 wx.* 蓝牙 API。

配置

1. 小程序后台(必须)

微信从 2023.10.17 起强制启用「用户隐私保护」:wx.openBluetoothAdapter 属于隐私接口,只有在小程序管理后台声明的接口才允许调用,未声明会直接被禁用。

在小程序管理后台依次进入:设置 → 基本设置 → 服务内容声明 → 用户隐私保护指引,勾选并声明:

  • 蓝牙(必需,对应 wx.openBluetoothAdapter)
  • 位置信息(仅当你在扫描前调用了 wx.getLocation 来触发安卓系统定位授权时才需要)

提交后等待审核通过。开发/体验阶段还需要在 开发管理 → 接口设置 中开通「蓝牙」接口权限。

若未配置,真机日志会出现 backgroundfetch privacy fail {... errno:101 ...},并且对应的隐私接口会被禁用。

2. 手机系统(安卓)

安卓 6.0 以上,微信搜索 BLE 设备依赖微信 App 的定位权限和系统定位开关:

  • 手机「设置 → 应用 → 微信 → 权限」允许定位
  • 打开手机下拉菜单中的「位置信息 / GPS」开关

正常情况下无需小程序再申请定位权限。若某些机型仍报 1509008 location permission is denied,说明微信客户端没有拿到系统定位权限,需要在小程序里主动调用一次 wx.getLocation 触发系统授权弹窗:

{
  "mp-weixin": {
    "permission": {
      "scope.userLocation": { "desc": "搜索蓝牙打印机需要定位权限" }
    },
    "requiredPrivateInfos": ["getLocation"]
  }
}
uni.getLocation({
  type: 'gcj02',
  complete: () => startScan(/* ... */)
})

并在《用户隐私保护指引》中同时声明「位置信息」。

iOS 无此要求。

3. 代码引用

import { startScan, connect, onConnectStateChange } from '@/uni_modules/xl-miniprint'

打印相关方法同样从该路径引入。

快速开始

onConnectStateChange((state) => {
  console.log(state.state, state.deviceId)
})

startScan((device) => {
  console.log(device.name, device.deviceId)
})

// 搜索到设备后连接
connect({ deviceId: 'xxx', mtu: 185 })

打印小票(ESC/POS)

escClear()
escInit()
escJustification(1)
escCharacterSize(0x11)
escLine('打印测试')
escCharacterSize(0)
escQrCode({ content: 'https://example.com', size: 5 })
escCut()
sendEscCommand()

打印标签

// TSPL
tscClear()
tscCls()
tscSize({ width: 76, height: 130 })
tscGap(0)
tscText({ x: 20, y: 20, font: 'TSS24.BF2', content: '测试标签' })
tscBarcode({ x: 20, y: 80, type: '128', height: 48, content: '12345678' })
tscPrint(1)
sendTscCommand()

// CPCL
cpclClear()
cpclSize({ width: 400, height: 480, copies: 1 })
cpclText({ x: 20, y: 40, font: '4', content: '测试标签' })
cpclBarcode({ x: 20, y: 120, type: '128', height: 80, content: '12345678' })
cpclPrint()
sendCpclCommand()

// ZPL
zplClear()
zplStart()
zplSize({ width: 600, height: 400 })
zplText({ x: 20, y: 20, font: '0', content: '测试标签' })
zplQrCode({ x: 400, y: 20, content: 'https://example.com' })
zplPrint(1)
zplEnd()
sendZplCommand()

打印图片

先用 canvas 取到 RGBA 像素数据,再传入对应的图片接口:

const image = { width: res.width, height: res.height, data: res.data }

escBitmap(image)                                  // 小票
tscBitmap({ x: 0, y: 0, mode: 0, image })         // TSPL
cpclBitmap({ x: 20, y: 20, image })               // CPCL
zplBitmapBinary({ x: 20, y: 20, image })          // ZPL

照片建议 dithering: true,文字/logo 可关闭抖动。图片宽度建议按打印机实际宽度输出(58mm 约 384 点,80mm 约 576 点)。

API

蓝牙

方法 说明
startScan(callback) 开始扫描,回调 BLEDevice
stopScan() 停止扫描
connect(options) 连接,{ deviceId, serviceId?, writeCharacteristicId?, notifyCharacteristicId?, mtu? }
disconnect() 断开连接
isConnected() 是否已连接
getConnectedDevice() 当前设备
onConnectStateChange(callback) 连接状态监听
onBluetoothStateChange(callback) 蓝牙开关监听
onDataReceived(callback) 打印机回传数据
onWriteProgress(callback) 发送进度
onError(callback) 错误监听
setMtu(options?) 设置 MTU(Android),成功后自动调整分包
getMtu() 当前 MTU
setChunkSize(size) 分包大小,默认 20
getChunkSize() 当前分包大小
setWriteInterval(ms) 包间隔,默认 0
getWriteInterval() 当前包间隔
writeBytes(data) 发送原始字节

缓冲区

方法 说明
escClear() / escGetData() 清空 / 获取 ESC/POS 缓冲区
tscClear() / tscGetData() 清空 / 获取 TSPL 缓冲区
cpclClear() / cpclGetData() 清空 / 获取 CPCL 缓冲区
zplClear() / zplGetData() 清空 / 获取 ZPL 缓冲区
sendEscCommand(clearAfter?) 发送 ESC/POS
sendTscCommand(clearAfter?) 发送 TSPL
sendCpclCommand(clearAfter?) 发送 CPCL
sendZplCommand(clearAfter?) 发送 ZPL

指令

  • ESC/POS:escInit、escText、escLine、escJustification、escBold、escCharacterSize、escBarcode、escQrCode、escBitmap、escCut、escSound 等
  • TSPL:tscSize、tscGap、tscCls、tscText、tscBar、tscBox、tscBarcode、tscQrcode、tscBitmap、tscPrint 等
  • CPCL:cpclSize、cpclText、cpclLine、cpclBox、cpclBarcode、cpclQrCode、cpclBitmap、cpclPrint 等
  • ZPL:zplSize、zplText、zplTextBlock、zplBox、zplBar、zplLine、zplBarcode、zplQrCode、zplBitmap、zplBitmapBinary、zplPrint 等

完整接口与参数类型见 utssdk/interface.uts 或示例页面。

注意

  1. 指令先写入各自的缓冲区,调用 sendXxxCommand() 后才会通过蓝牙发送。
  2. 请先扫描并连接成功,再发送打印指令。
  3. 默认 20 字节分包、0ms 间隔;调用 setMtu({ mtu: 185 }) 或 setChunkSize(180) 可明显提速。出现乱码/丢数据时降低分包或增大包间隔。
  4. iOS 的 deviceId 是系统 UUID,Android 通常是 MAC 地址。
  5. ZPL 中文默认使用 ^CI26 代码页,可通过 zplCodePage() 调整。
  6. 安卓上 BLE 设备被连接后会停止广播,且系统会缓存 GATT 客户端。插件在每次 startScan() 前会自动 closeBluetoothAdapter() 再重新打开,避免"第二次搜索不到设备"。因此扫描开始会有约 0.3–1s 的延迟。
  7. 控制台出现 backgroundfetch privacy fail ... errno:101 表示对应隐私接口未在《用户隐私保护指引》中声明。若功能正常可忽略,正式发布前请在小程序后台补齐声明。

示例

  • pages/index/index.vue:首页,连接状态、传输设置、小票/标签/图片打印
  • pages/index/device.vue:蓝牙搜索页,连接成功后自动返回首页

参考

隐私、权限声明

1. 本插件需要申请的系统权限列表:

微信小程序:需要 scope.userLocation(Android 搜索蓝牙需要定位权限)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

蓝牙设备信息仅用于连接打印机,不会上传服务器

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无