更新记录

1.0.1（2026-03-25）

一、文档更新

1.0.0（2026-03-17）

一、新版本首发

平台兼容性

uni-app(4.72)

其他

蓝牙打印 UTS 插件 (hl-bluetooth-print)

插件简介

本插件封装了 Android 经典蓝牙（SPP）通信，支持蓝牙打印机的搜索、连接、状态获取和 CPCL 指令打印。适配芝柯和爱印品牌打印机。

平台支持

使用说明

导入插件

import {
 enableDebugLog,
 onLogCallback,
 onStartScan,
 stopScan,
 connect,
 disconnect,
 getPrinterStatus,
 printCommand,
 isConnected,
 release
} from '@/uni_modules/hl-bluetooth-print'

基本使用示例

// 1. 开启调试日志（可选）
enableDebugLog()

// 2. 设置日志回调（可选）
onLogCallback((level, tag, message) => {
 console.log(`[${level}] ${tag}: ${message}`)
})

// 3. 搜索蓝牙设备
onStartScan({
 timeout: 12000,
 onFound: (device) => {
  console.log('发现设备:', device.name, device.address)
 },
 onFinish: (devices) => {
  console.log('搜索完成，共发现', devices.length, '个设备')
 }
})

// 4. 连接打印机
connect({
 address: 'XX:XX:XX:XX:XX:XX',
 brand: 'zhike', // 'zhike'(芝柯) | 'aiyin'(爱印) | 'auto'(自动)
 onSuccess: (result) => {
  console.log('连接成功:', result.message)
 },
 onFail: (result) => {
  console.log('连接失败:', result.message)
 }
})

// 5. 查询打印机状态
getPrinterStatus((status) => {
 console.log('状态:', status.message, 'code:', status.code)
 // code: 0=正常, 1=缺纸, 2=开盖, -1=异常
})

// 6. 发送指令打印 (支持普通文本 CPCL/ZPL/TSPL/ESC 或 Base64)
printCommand({
 command: '! 0 200 200 830 1\nPW 580\n...省略...\nPRINT\n',
 // commandBase64: '...base64数据...', // 当遇到文本无法表达的16进制字节时可用 Base64
 // encoding: 'GBK', // 可选，默认为 GBK
 onSuccess: (result) => {
  console.log('打印成功:', result.message)
 },
 onFail: (result) => {
  console.log('打印失败:', result.message)
 }
})

// 7. 断开连接
disconnect()

// 8. 释放资源（页面销毁时调用）
release()

API 参数说明

ScanOptions 搜索选项

ConnectOptions 连接选项

PrintOptions 打印选项

BluetoothDevice 蓝牙设备信息

PrinterStatus 打印机状态

ConnectResult / PrintResult 结果

支持的打印机品牌

CPCL 指令示例

! 0 200 200 830 1
PW 580
GAP-SENSE
TEXT 24 00 460 10 第1次打印
CENTER 576
SETMAG 4 4
TEXT 55 00 0 65 无单货物
B 128 2 30 110 0 140 123123
SETMAG 2 2
TEXT 55 00 0 260 123123
LEFT
TEXT 55 00 120 320 日期: 2026-03-05
LINE 200 360 500 360 2
TEXT 55 0 120 390 班次: 早班
PR 0
FORM
PRINT

App 负责生成完整的 CPCL 指令，插件仅负责发送到打印机。

注意事项

1. 权限要求：Android 需要蓝牙权限和位置权限，插件会自动申请。
2. 编码格式：CPCL 指令使用 GBK 编码发送，支持中文打印。
3. 分块发送：大数据量指令会自动分块发送（每块 1024 字节），避免打印机缓冲区溢出。
4. 资源释放：页面销毁时请调用 release() 释放蓝牙资源。
5. 品牌选择：若不确定品牌，可使用 auto 模式，插件会自动尝试匹配。