更新记录

1.0.0（2026-11-02）

首次发布，支持 Android 平台（最低 SDK 21，需设备支持 USB Host / OTG）。

• USB：设备枚举、打印机枚举、USB 连接（权限申请 + 插拔监听 + 关闭连接回调）
• 画布打印：画线、边框、文字、区域文字、条码、区域条码、二维码、图片、区域图片、提交打印
• TSPL 标签打印：纸宽高、页设置、线、边框、文本、区域文本、条码、二维码、图片、区域图片、提交、翻转、擦除、标签设置、间隙、蜂鸣、原始指令、钱箱（19 个方法）
• 通用打印：文本、图片（压缩 / 浓度 / 灰度 / 针打）、表格、条码二维码、纸宽、页设置、初始化、字体、打印属性、编码集、钱箱、切纸、缺纸 / 纸将尽 / 状态查询、十六进制互转

平台兼容性

uni-app(4.72)

uni-app x(4.72)

zy-usb-print（USB 热敏打印机）

Android 平台 USB 热敏打印机 UTS 原生插件，覆盖 USB 设备枚举与连接、画布打印、TSPL 标签打印、 通用 ESC/POS 打印，所有方法统一 { code, message, data } 回调结构。

功能特性

• USB 方式：枚举所有 USB 设备 / USB 打印机设备、USB 连接（自动申请权限、插拔监听、关闭回调）
• 画布打印：画线、边框、文字、区域文字、条形码、区域条形码、二维码、图片、区域图片、提交打印
• TSPL 标签打印：纸张宽高、页设置、线、边框、文本、区域文本、条码、二维码、图片、区域图片、 提交打印、翻转区域、擦除区域、标签设置、标签间隙、蜂鸣器、原始指令、钱箱（共 19 个方法）
• 通用打印（ESC/POS）：文本、图片（压缩 / 浓度 / 灰度 / 针打）、表格、条码二维码、纸张宽度、 页设置、初始化、字体样式、打印属性、编码集、钱箱、切纸、缺纸 / 纸将尽 / 状态 / 打印结果查询、 十六进制与字节数组互转

环境要求

引入

按需引入用到的方法：

import { usbConnect, printText, printTable, cutPaper } from '@/uni_modules/zy-usb-print'

回调结构

所有方法统一通过 callback(res => {}) 返回：

{
  code: 0,          // 0 成功，其余为错误码
  message: '',      // 消息提示
  data: {}          // 业务数据（无数据时为空对象）
}

错误码

一、USB 方式

getAllUsbDevices

获取所有 USB 设备。

getAllUsbDevices(res => {
  // res.data.list = [{ deviceName, deviceId, productId, productName, vendorId, deviceClass }]
})

getAllUsbPrinterDevices

获取所有 USB 打印机设备（接口类为 7），返回结构同上。

usbConnect

USB 连接。回调可持续触发：连接结果、USB 插入 / 拔出、关闭连接都通过同一个 callback 推送。

usbConnect({ deviceName: '/dev/bus/usb/001/003' }, res => {
  // res.code 0 连接成功 / -101 失败 / -103 未发现设备 / -104 无权限
  //          -105 usb插入 / -106 usb拔出 / -102 连接关闭
})

首次连接会弹出系统 USB 授权框，授权后自动完成连接（最长等待 20 秒）。

二、画布打印

画布打印分为两步：先用 drawXxx 把内容画到画布，再调用 print 提交给打印机。

drawLine（画线）

drawBorder（画边框）

drawText（画文字）

drawTextForArea（画区域块文字）

drawBarCode（画条形码）

barcodeType 可选值：UPC_E、CODABAR、ITF、CODE39、CODE93、CODE128、EAN8Plus2、 EAN8Plus5、EAN13Plus2、EAN13Plus5、JAN3_EAN13、JAN8_EAN8、JAN128、MSI、Postnet、 QR、UPC_A、UPCAPlus2、UPCAPlus5、UPCEPlus2、UPCEPlus5

drawBarCodeForArea（画区域块条形码）

参数为 drawBarCode 的全部参数 + areaStartX / areaStartY / areaEndX / areaEndY / xAlign / yAlign。

drawQrCode（画二维码）

drawGraphic（画图）

drawGraphicForArea（区域画图）

额外参数：areaStartX / areaStartY / areaEndX / areaEndY / bmpSizeX / bmpSizeY / xAlign / yAlign。

print（提交打印）

drawText({ textX: 10, textY: 10, text: '画布打印示例', fontSize: 'Size_32' }, () => {})
drawQrCode({ startX: 10, startY: 60, text: 'https://uniapp.dcloud.net.cn' }, () => {})
print({ rotate: 'Rotate_0', skip: 3 }, res => console.log(res))

三、TSPL 标签打印

TSPL 指令用于标签打印机（如 100mm×150mm 标签），同样是先设置/绘制，最后 printTSPL 提交。

setPaperWidthAndHeightTSPL({ width: 440, height: 1500 }, () => {})
pageSetupTSPL({ paperSizeType: 'SIZE_108mm', pageWidth: 440, pageHeight: 1500 }, () => {})
drawTextTSPL({ startX: 20, startY: 20, text: '标签标题', xMultiplication: 2, yMultiplication: 2 }, () => {})
drawBarCodeTSPL({ startX: 20, startY: 80, barcodeType: 'CODE128', height: 60,
  narrowWidth: 2, wideWidth: 4, isReadable: true, text: '1234567890' }, () => {})
draw2DBarCodeTSPL({ startX: 20, startY: 160, barcodeType: 'QR', level: 4, width: 6, text: 'zy-usb-print' }, () => {})
printTSPL({ numbers: 1 }, res => console.log(res))

四、通用方法（ESC/POS）

close（关闭连接）

close(res => console.log(res))

sendBytesData（发送字节数据）

printText（打印文本）

printImageWithCompressed（打印图片·压缩）

printImageWidthLevel（打印图片·浓度）

参数同上，isCompressed 换成 level（浓度等级，默认 0）。

printColorImg2Gray（打印灰色图片）

printImageStylus（针打图形）

printTable（打印表格）

printTable({
  column: '品名;数量;单价;金额',
  regular: ';',
  columnWidth: [14, 6, 6, 6],
  rows: ['保鲜袋;1;10.00;10.00', '铁丝挂钩;2;5.00;10.00', '雨伞;3;5.00;15.00']
}, res => console.log(res))

printBarCode（打印条码和二维码）

getPaperWidth（获取纸张宽度）

回调 data.width。

setPaperWidth（设置纸张宽度）

pageSetup（页设置·画布）

initPrinter（初始化打印机）

setFont（设置字体样式）

setPrinter（设置打印属性）

getCharsetName（获取编码集）

回调 data.charsetName（默认 GBK）。

setCharsetName（设置编码集）

openCashBox（打开钱箱）

cutPaper（切纸）

isPaperOut（是否缺纸）

回调 data.isPaperOut。

isPaperWillOut（纸张是否将用尽）

回调 data.isPaperWillOut。

getCurrentStatus（获取打印机状态）

回调 data.status：0 正常 / -1 写入数据失败 / -2 缺纸 / -3 纸将尽 / -4 开盖 / -5 读数据失败。

getPrintingStatus（获取打印结果状态）

回调 data.status：0 打印完成 / -1 未知异常 / -2 正在打印中 / -3 缺纸 / -4 纸舱盖开盖 / -5 与打印机通信失败 / -6 通信异常 / -7 接收数据格式不正确。

hexStringToByteArray（十六进制字符串转字节数组）

回调 data.bytes（Number[]）。

stringToHex（字符串转 16 进制）

回调 data.value（小写十六进制字符串）。

五、完整示例

import {
  getAllUsbPrinterDevices,
  usbConnect,
  initPrinter,
  setPrinter,
  setFont,
  printText,
  printTable,
  printBarCode,
  cutPaper
} from '@/uni_modules/zy-usb-print'

// 1. 查找打印机并连接
getAllUsbPrinterDevices(res => {
  if (res.code !== 0 || res.data.list.length === 0) {
    return console.log('未发现打印机')
  }
  const deviceName = res.data.list[0].deviceName
  usbConnect({ deviceName }, conn => {
    console.log('连接回调', conn.code, conn.message)
    if (conn.code === 0) {
      printReceipt()
    }
  })
})

// 2. 打印小票（ESC/POS）
function printReceipt() {
  initPrinter(() => {})
  setPrinter({ command: 'ALIGN', value: 1 }, () => {})
  setFont({ width: 1, height: 1, bold: 1 }, () => {})
  printText({ content: '欢迎光临\n' }, () => {})
  setFont({ width: 0, height: 0, bold: 0 }, () => {})
  printText({ content: '订单号：20261031001\n' }, () => {})
  printTable({
    column: '品名;数量;金额',
    columnWidth: [16, 6, 8],
    rows: ['美式咖啡;1;18.00', '芝士蛋糕;2;36.00']
  }, () => {})
  printBarCode({ type: 'QRCODE', width: 4, height: 4, level: 4, content: 'https://example.com/order/20261031001' }, () => {})
  printText({ content: '合计：54.00 元\n\n\n' }, () => {})
  cutPaper({ isHalf: false }, res => console.log('切纸', res.code))
}

注意事项

1. 必须使用自定义基座：插件包含原生代码，标准基座不包含该插件。
2. USB 授权：首次连接会在系统弹窗中请求 USB 权限，用户拒绝或 20 秒未操作返回 -104； 部分机型需在系统设置中为 App 打开「USB 权限」。
3. text 参数换行：printText 使用 \n 换行；TSPL 原始指令使用 \r\n。
4. 图片来源：
   • path：手机本地文件路径，推荐用 uni.chooseImage 取临时路径（插件已兼容 file:// 前缀）， 也支持 /sdcard/xxx.png 这类绝对路径（Android 10+ 访问公共目录需存储权限或使用应用私有目录）
   • drawable：宿主 App 的 drawable 资源名（插件自身不携带图片资源，需宿主项目提供）
   • assets：宿主 App 的 assets 内路径
5. 画布打印：drawXxx 只是把内容绘制到画布，必须调用 print 才会真正打印； 打印前建议先 initPrinter 清空画布。
6. TSPL 与 ESC/POS 是两套指令集：小票机用 printText 等通用方法，标签机用 drawXxxTSPL + printTSPL。

实现说明