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

收藏人数:
购买普通授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 895
赞赏 8
下载 12769501
赞赏 1959
赞赏
京公网安备:11010802035340号