更新记录

1.0.0（2026-08-07）

Android CPCL+ESC 蓝牙/WiFi/UDP 发现； iOS CPCL 蓝牙/WiFi/LAN 发现； 保留 connectBluetooth / connectWifi 与 startWifiScan。 USB 待后续版本。

平台兼容性

uni-app(4.11)

breao-hprtprint 使用说明

汉印（HPRT）便携热敏打印 UTS 插件。面向 uni-app Vue3 的 App 端（Android / iOS）。

当前版本：1.0.0

• Android：CPCL + ESC；蓝牙、WiFi、UDP 局域网发现
• iOS：CPCL；蓝牙、WiFi、LAN 发现
• USB：尚未封装

1. 环境要求

• HBuilderX 4.11 及以上
• uni-app Vue3
• 仅 App-Android / App-iOS（不支持 H5、小程序、鸿蒙）
• 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包（不支持离线打包、安心打包）
• 授权绑定唯一 appid + 包名
• printBytes 建议 HBuilderX 4.51 及以上

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-hprtprint，或从插件市场导入后同步。

业务代码引用：

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  connectBluetooth,
  startWifiScan,
  stopWifiScan,
  connectWifi,
  disconnect,
  printText,
  printBytes,
  getConnectionState,
} from '@/uni_modules/breao-hprtprint'

示例组件：uni_modules/breao-hprtprint/components/hprt-print-demo/hprt-print-demo.vue

3. 快速开始

3.1 蓝牙（CPCL 标签机，如 HM-A300）

init({
  driver: 'cpcl',
  transport: 'bluetooth',
  modelHint: 'HM-A300',
  debug: true,
  onDisconnected(res) {
    console.log('被动断开', res.address)
  },
  success() {
    startBluetoothScan({
      timeout: 10000,
      strictFilter: false,
      includeBonded: true,
      success(res) {
        const d = res.devices && res.devices[0]
        if (!d) return
        connectBluetooth({
          address: d.address,
          timeout: 15000,
          success() {
            printText({
              content: 'Hello HPRT\n第二行',
              pageWidth: 384,
            })
          },
        })
      },
    })
  },
})

3.2 WiFi / 局域网（Android 建议 ESC）

init({
  driver: 'esc',
  transport: 'wifi',
  success() {
    startWifiScan({
      timeout: 5000,
      success(res) {
        const d = res.devices && res.devices[0]
        if (!d) {
          // 也可手填 IP
          connectWifi({ ip: '192.168.1.100' })
          return
        }
        connectWifi({
          ip: d.ip,
          timeout: 15000,
          success() {
            printText({ content: 'WiFi OK' })
          },
        })
      },
    })
  },
})

用毕调用 disconnect 与 destroy。

4. API 说明

回调约定：各方法支持 success / fail / complete（与 uni-app 常见异步 API 一致）。

5. 能力矩阵

路由提示：

• driver: 'auto' 且 modelHint 含 E200 / E300 / TP80 等走 ESC，否则默认 CPCL
• transport: 'wifi' 且 driver: 'auto' 时默认 ESC

6. 权限说明

Android

• 蓝牙：BLUETOOTH、BLUETOOTH_ADMIN（API 不超过 30）；BLUETOOTH_SCAN、BLUETOOTH_CONNECT（Android 12+）
• 定位：ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION（经典蓝牙扫描在多数机型需要）
• 网络：INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE、CHANGE_WIFI_STATE（局域网打印与 UDP 发现）

iOS

• NSBluetoothAlwaysUsageDescription
• NSBluetoothPeripheralUsageDescription

插件不采集、不上传任何数据。打印内容仅经本机蓝牙或局域网发至已连接的汉印打印机。集成汉印官方 SDK 仅用于本地设备通信。

7. 平台注意

iOS

• 蓝牙连接须先 startBluetoothScan，再使用结果中的 address（优先 MAC，否则 UUID）
• driver: 'esc' 返回 9020010
• Info.plist 已含蓝牙用途说明；真机须自定义基座

Android ESC

• 与 CPCL 可同包（类路径分离）
• 票据机建议：HM-E200 / E300、TP801 / TP805 等
• 局域网发现请使用 driver: 'esc'

WiFi

• 手机与打印机须同一局域网
• 可手填 IP，或先 startWifiScan 再 connectWifi
• Android CPCL 无 UDP 发现 API，调用 startWifiScan 返回 9020010

8. 错误码