更新记录

1.06（2026-08-15） 下载此版本

汉印 HPRT CPCL 打印机 UTS 插件 使用说明 支持 Android 平台蓝牙 / WiFi 打印

平台兼容性

uni-app(4.15)

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

PrintModuleCPCL —— 汉印 HPRT CPCL 打印机 UTS 插件 使用说明

本插件由原生 nativeplugin（com.hprt.uni.cpcl.PrintModuleCPCL + lib_uni_cpcl_v1.05.aar）改写为 UTS 插件， 底层直接调用 CPCL SDK 的 cpcl.PrinterHelper 静态方法，支持 Android 平台蓝牙 / WiFi 打印。

一、目录结构

uni_modules/PrintModuleCPCL/
├── package.json                       # 插件元信息（type: "uts"）
├── utssdk/
│   ├── interface.uts                  # 对外 API 声明（IDE 类型提示 & 桥接契约）
│   └── app-android/
│       ├── index.uts                  # Android(Kotlin) 实现
│       ├── config.json                # 编译配置 + 支持的 abi
│       └── libs/
│           ├── lib_uni_cpcl_v1.05.aar # 汉印 CPCL SDK 封装 AAR
│           ├── arm64-v8a/libLZO.so
│           ├── armeabi-v7a/libLZO.so
│           ├── x86/libLZO.so
│           └── x86_64/libLZO.so
└── 使用说明.md                        # 本文件

libs/ 下的 AAR 与 .so 会被 uni-app 自动打包到自定义基座 / APK 中，无需额外 gradle 配置。

二、与原生插件的差异（重要）

对比项 原生插件 本 UTS 插件
引入方式 uni.requireNativePlugin('PrintModuleCPCL') import { ... } from '@/uni_modules/PrintModuleCPCL'
返回值 JSONObject + UniJSCallback 回调 { result: <int> } 同步返回值（int 失败 -1 / string 失败 ""）
异步事件 setDisConnectBTListener 回调 仅 setDisConnectBTListener 保留回调（蓝牙断开为异步）
异常 内部吞掉或回调错误 捕获并记录日志，不闪退

SDK 本身是同步的，因此改为同步返回后，TS 侧更易判空、串联调用。

三、快速开始

1. 制作自定义调试基座

UTS 原生插件不会进入标准基座。在 HBuilderX 中： 运行 → 运行到手机或模拟器 → 制作自定义基座，勾选本插件后等待云打包完成，再用自定义基座运行。

2. 在页面中调用（Vue2 示例）

// 注意：Vue2 项目必须用 @ 路径（不能用 uni.requireNativePlugin）
import { connectionBT, printAreaSize, printText, print } from '@/uni_modules/PrintModuleCPCL'

// 连接
const code = connectionBT({ address: 'DC:1D:30:7C:74:96' }) // 0 = 成功
if (code !== 0) { uni.showToast({ title: '连接失败', icon: 'none' }); return }

// 设置纸张（标签纸高度 400，打印 1 份）
printAreaSize({ height: '400', number: '1' })
// 添加文本（direction 方向 / fontSize 字号 / x_pos,y_pos 坐标 / data 内容）
printText({ direction: '0', fontSize: '55', x_pos: '10', y_pos: '10', data: 'Hello HPRT' })
// 走纸并打印
print()

完整可运行示例见 pages/print-demo/print-demo.vue（已注册路由）。

四、API 列表

所有 int 返回：成功视具体接口而定（通常 0），失败返回 -1； 所有 string 返回：失败返回 ""。坐标/尺寸参数均为字符串。

连接 / 端口

方法 参数 返回 说明
connectionBT { address: string } number 蓝牙连接，address 为 MAC
connectionWIFI { address: string } number WiFi 连接，address 为 IP
closeBT — void 断开当前连接
getEndStatus { outTime: number } number 获取纸尽状态
setDisConnectBTListener callback: (res) => void void 蓝牙断开监听（异步），断开回调 { result: 0 }

打印页面 / 指令

方法 参数 返回 说明
printAreaSize { height: string, number: string } number 设置打印区域（高度、份数）
setPageType { pageType: number } void 设置纸张类型（0 收据 / 1 标签…）
printForm — number FORM 指令
print — number 打印并走纸

文本 / 条码 / 二维码

方法 参数 返回 说明
printText { direction, fontSize, x_pos, y_pos, data } number 打印文本（第 3 参固定 "0"）
setCodePage { codePage, language } number 设置代码页
setLanguageEncode { language } void 设置语言编码（影响 writeTextData 字节编码）
printBarCode { rotation, code_type, width, ratio, height, x_pos, y_pos, undertext, number, offset, code_data } number 打印条码
printQRCode { rotation, x_pos, y_pos, mode, width, code_data } number 打印二维码
printBox { leftX, leftY, rightX, rightY, width } number 打印方框
printLine { startX, startY, endX, endY, width } number 打印线条
setMag { widthMag, heightMag } number 设置放大倍数
setAlign { align } number 设置对齐（LEFT/CENTER/RIGHT）
printPDF417 { command, start_x, start_y, xd, yd, c, s, data } number 打印 PDF417
setTextBox { startX, startY, width, fontSize, isBole, isDouble, str } number 文本框（自动换行）
printBackground { startX, startY, fontSize, background, data } number 背景文字

printBarCode 的 code_type 取值（来自 SDK 常量）： 128 / 39C / 93 / CODABAR / CODABAR16 / EAN13 / EAN8 / UPCA / UPCE / I2OF5 / MSI / UCCEAN128 / PDF417 等。 printQRCode 的 mode（纠错级别）：L / M / Q / H。

数据透传

方法 参数 返回 说明
writeData { bData: number[] } number 发送原始字节（0–255）
writeTextData { text: string } number 按当前编码发送文本
readData { time: number } string 读取返回数据（十六进制字符串）

位图打印

方法 参数 返回 说明
printBitmapBase64 { base64, x_pos, y_pos, halftoneType } number base64 位图（不含 data: 前缀）
printBitmapPath { path, x_pos, y_pos, halftoneType } number 图片文件路径位图

halftoneType：0 = 普通，1 = 抖动（halftone）。

状态 / 信息查询

方法 参数 返回 说明
getPrinterStatus — number 打印机状态（0 正常）
getPrintSN — string 序列号
getElectricity — number 电量
getVoltage — string 电压
getPrinterVersion — string 固件版本

其它 / 日志

方法 参数 返回 说明
setContrast / setSpeed / setSp / preFeed / setBold / setCountry / setBluetoothName / setLayer / openEndStatic / poPrint / saveParameter / setInverseLine 见 interface.uts number/void 各类打印参数设置
setLog { isPrint: boolean } void 开启 / 关闭 SDK 内部日志

五、典型打印流程

connectionBT()          // 1. 建立连接（0=成功）
  ↓
printAreaSize()         // 2. 设定纸张大小 & 份数
  ↓
printText / printBarCode / printQRCode / printBitmapBase64   // 3. 添加内容（可多次）
  ↓
print()                 // 4. 走纸并输出
  ↓
closeBT()               // 5. 断开（可选，建议页面 onUnload 时调用）

六、权限说明

package.json 已声明所需权限（蓝牙 / 网络 / 存储）： BLUETOOTH、BLUETOOTH_ADMIN、BLUETOOTH_CONNECT、BLUETOOTH_SCAN、 INTERNET、ACCESS_WIFI_STATE、ACCESS_NETWORK_STATE、READ/WRITE_EXTERNAL_STORAGE。 Android 12+（BLUETOOTH_CONNECT/SCAN）需在运行时动态申请，请配合 uni.authorize / 系统权限弹窗处理。

七、常见问题（FAQ）

Q1：调用方法报 module not found / 方法 undefined？

  • 确认已用自定义基座运行（标准基座不含 UTS 原生插件）。
  • 确认 import 路径为 @/uni_modules/PrintModuleCPCL，且 manifest.json 中没有旧的 nativePlugins.PrintModuleCPCL 声明（二者同 id 会冲突，本插件已删除该声明）。

Q2：编译报 ABI 不支持（如 armeabi / mips）？

  • 旧原生插件 libs 含不被 uni-app 支持的 ABI。本插件 config.json 仅保留 arm64-v8a / armeabi-v7a / x86 / x86_64，并已清理冗余 .so。如仍报错，删除 nativeplugins/PrintModuleCPCL 冗余目录即可。

Q3：蓝牙连上了但打印没反应？

  • 检查 printAreaSize 的 height 是否匹配实际纸张；内容添加后必须调用 print() 才会输出。
  • 打开日志：setLog({ isPrint: true })，在 Logcat 中过滤 PrinterHelper。

Q4：能用于 iOS 吗？

  • 不能。本插件仅封装 Android 的 CPCL SDK，平台声明为 Android only。

八、与原生插件对照（迁移清单）

原生插件（回调式） UTS 插件（同步式）
module.connectionBT({address}, cb) connectionBT({ address }) → number
module.printText({...}, cb) printText({...}) → number
module.print({...}, cb) print() → number
module.getPrintSN({}, cb) getPrintSN() → string
module.setDisConnectBTListener(cb) setDisConnectBTListener(cb)（回调保留）

隐私、权限声明

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

<uses-permission android:name="android.permission.BLUETOOTH"/> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

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

插件不采集任何数据

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

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉

暂无用户评论。