更新记录

1.0.0（2026-09-11） 下载此版本

• 首个版本
• 蓝牙 / WiFi 连接，蓝牙扫描（含已配对设备）
• ESC/POS 小票打印：整单 printReceipt + 单步接口（文本/条码/二维码/图片/切纸/蜂鸣/自检）
• TSPL 标签打印：printLabel（文本/条码/二维码/图片/框/线，份数/浓度/速度）
• CPCL 移动标签打印：printCpcl（文本/条码/二维码/图片/线/框/蜂鸣/切纸）
• ZPL 标签打印：printZpl（自动 ^XA...^XZ，文本/条码/二维码/图片/框/切纸）
• 打印机状态查询、设备信息查询
• Android 12+ 动态蓝牙权限申请
• 默认 GBK 编码，支持自定义

平台兼容性

uni-app(4.45)

yk-hprt-printer 汉印打印机插件

基于汉印官方 UxPrint Android SDK (v1.00.03) 封装的 uni-app 打印机 UTS 插件。

功能特性

• 四种打印协议：ESC/POS（收银小票）、TSPL（标签）、CPCL（移动标签）、ZPL（Zebra 协议标签）
• 多种连接方式：蓝牙（经典蓝牙）、WiFi（同一局域网，默认端口 9100）
• 丰富的打印元素：文本、条码（CODE128/CODE39/EAN13/EAN8/UPCA/UPCE/ITF/CODABAR）、二维码、图片（本地文件/base64）、线条、矩形框
• 设备能力：实时状态查询（缺纸/开盖/过热等）、设备信息（机型/序列号/固件版本/电量）、切纸、蜂鸣、自检页
• 中文友好：默认 GBK 编码，支持自定义编码
• Promise 风格 API，配套完整 TypeScript 类型声明（interface.uts）

环境要求

安装

1. 插件市场导入（推荐）：本项目详情页点击「使用 HBuilderX 导入插件」
2. 手动安装：将整个 hprt-printer 目录复制到项目的 uni_modules/ 下

权限已由插件内 AndroidManifest.xml 自动声明（蓝牙/定位/网络），无需额外配置。

因插件含原生 AAR，真机调试需先「制作自定义调试基座」；正式打包用云打包即可。

快速上手

import * as hprt from '@/uni_modules/yk-hprt-printer'

// 1. 申请权限并扫描（Android 12+ 必须）
await hprt.requestBluetoothPermission()
await hprt.startBluetoothScan()
// 轮询获取设备
const devices = JSON.parse(await hprt.getDiscoveredDevices())

// 2. 连接（蓝牙 MAC 或 WiFi IP）
await hprt.connect({ type: 'bluetooth', address: '00:11:22:33:44:55' })
// await hprt.connect({ type: 'wifi', ip: '192.168.1.100', port: 9100 })

// 3. 打印小票（ESC/POS）
await hprt.printReceipt({
  lines: [
    { type: 'init' },
    { type: 'align', align: 'center' },
    { type: 'text', text: '汉印小票', fontSize: 32, bold: true },
    { type: 'barcode', data: '123456789012', barcodeType: 'CODE128', height: 80 },
    { type: 'qrcode', data: 'https://www.hprt.com', size: 6 },
    { type: 'feed', lines: 4 },
    { type: 'cut' }
  ]
})

// 4. 打印标签（TSPL）
await hprt.printLabel({
  width: 60, height: 40, copies: 1,
  items: [
    { type: 'text', text: '商品名称', x: 20, y: 15, fontSize: 24, bold: true },
    { type: 'qrcode', data: 'https://www.hprt.com', x: 400, y: 15, size: 4 }
  ]
})

API 一览

初始化 / 权限

扫描

连接

状态 / 信息

ESC/POS 小票

• printReceipt(options) — 整单打印（推荐），行类型：init / text / barcode / qrcode / image / align / feed / cut / beep / selfTest
• 单步接口：printText / printBarcode / printQRCode / printImage / cutPaper(feedLines) / selfTest()

TSPL 标签

• printLabel(options) — 参数：width/height（mm，必填）、gap/density/speed/direction/copies/encoding
• 元素类型：text / barcode / qrcode / image / box / bar / line（x/y 坐标为点）

CPCL 移动标签

• printCpcl(options) — 参数：length（点，必填）、offset/hdpi/vdpi/direction/speed/contrast/formFeed
• 元素类型：align / text / barcode / qrcode / image / line / box / beep / cut（line/box 用右下角坐标 x2/y2）

ZPL 标签

• printZpl(options) — 自动生成 ^XA...^XZ 框架，参数：printWidth/labelLength/speed/darkness/encoding
• 元素类型：text / barcode / qrcode / image / box / cut；orientation：N/R/I/B

完整参数说明见插件内 utssdk/interface.uts 类型声明（编辑器有代码提示）。

常见问题

1. 真机运行提示插件不存在：含 AAR 的插件必须先制作自定义调试基座
2. 扫描不到设备：检查蓝牙权限（Android 12+「附近设备」、低版本定位权限）、蓝牙开关
3. 中文乱码：默认 GBK，可用 encoding: 'UTF-8' 覆盖
4. 图片路径：uni.chooseImage 临时路径需 plus.io.convertLocalFileSystemURL() 转绝对路径
5. 标签空白：检查标签尺寸参数与实际纸张是否一致

更新日志

• 1.0.0 首个版本：蓝牙/WiFi 连接、ESC/POS、TSPL、CPCL、ZPL 打印