更新记录

2.0.0(2026-11-03)

  • 新增二维码纠错等级支持(QrcodeParam.errorLevel,可选 L/M/Q/H,默认 M);
  • 补全 Android USB 打印:设备列表、插拔监听、权限申请与连接;
  • 新增 Android/iOS Wi-Fi 打印:通过 IP + 端口直连;

1.0.1(2026-07-08)

  • 修复已知问题;

1.0.0(2025-10-08)

  • 支持安卓、iOS蓝牙;
  • 添加常用指令接口;
查看更多

平台兼容性

uni-app(4.75)

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

uni-app x(4.75)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - 5.0 12 - -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

欢迎使用 xl-hmA300 插件

🧾 汉印 HM-A300 系列蓝牙打印 SDK 接口说明文档

本文档详细介绍汉印 A300 系列打印 SDK(蓝牙 / Android USB)的 TypeScript 接口定义及说明,适用于调用打印机进行标签打印、二维码、条码、图像及文本输出等操作。


📖 目录


🔌 蓝牙操作

1. 获取蓝牙状态

getBluetoothState(callback: BooleanBack): void

说明: 获取当前蓝牙开关状态。

参数名 类型 必填 说明
callback (ok: boolean) => void ✅ 蓝牙状态回调,true 表示开启,false 表示关闭

2. 扫描蓝牙

scanBlue(callback: BlueDeviceBack): void

扫描附近的蓝牙设备。

参数名 类型 必填 说明
callback (device: HBlueDevice) => void ✅ 每发现一个蓝牙设备都会回调一次

HBlueDevice 类型说明:

字段 类型 必填 说明
deviceId string ✅ 蓝牙设备唯一标识(Android: MAC 地址 / iOS: UUID)
name string ✅ 蓝牙设备名称
paired boolean ❌ 是否已配对,仅 Android 有效

3. 停止扫描蓝牙

stopScanBlue(): void

停止蓝牙扫描,无参数。


4. 连接蓝牙

connectBlue(deviceId: string, callback: NumberBack): void

连接指定蓝牙打印机。

参数名 类型 必填 说明
deviceId string ✅ 蓝牙设备 ID
callback (result: number) => void ✅ 连接结果回调

返回值:

数值 含义
0 连接成功
-1 连接超时
-2 蓝牙地址格式错误
-3 打印机与 SDK 不匹配(握手失败)

5. 断开连接

disconnect(): boolean

说明: 断开当前蓝牙连接。
返回值:

  • true:断开成功
  • false:断开失败

6. 获取打印机序列号

getSN(callback: StringBack): void
参数名 类型 必填 说明
callback (result: string) => void ✅ 返回打印机 SN 编号

🔌 USB 打印(Android)

iOS 暂不支持 USB 打印:getUsbDeviceList() 返回空数组,connectUsb() 回调 -1。

获取 USB 设备列表

getUsbDeviceList(): HUsbDevice[]

返回当前已连接的 USB 打印机设备(按 USB Printer 接口类过滤)。

字段 类型 说明
deviceName string USB 设备名称
deviceId string USB 设备 ID
productName string 产品名称
productId string 产品 ID
vendorId string 供应商 ID
manufacturerName string 生产商名称

监听 USB 插拔

onUsbAttached(callback: UsbDeviceBack): void
onUsbDetached(callback: UsbDeviceBack): void

连接 USB 打印机

connectUsb(deviceId: string, callback: NumberBack): void
参数名 类型 必填 说明
deviceId string ✅ getUsbDeviceList() 返回的 ID
callback (result: number) => void ✅ 0 成功,-1 失败

首次连接会弹出系统 USB 访问权限授权框,授权成功后自动连接。连接成功后,后续 printAreaSize、text、barcode、qrCode、print 等打印接口与蓝牙方式完全一致。

const usbList = getUsbDeviceList()
if (usbList.length > 0) {
  connectUsb(usbList[0].deviceId, (result) => {
    if (result === 0) {
      printAreaSize({ height: 60 * 8, qty: 1 })
      pageWidth(60 * 8)
      text({ x: 10, y: 10, font: '16', content: 'USB 打印测试' })
      print()
    }
  })
}

📶 Wi-Fi 打印

连接 Wi-Fi 打印机

connectWifi(ip: string, port: string, callback: NumberBack): void
参数名 类型 必填 说明
ip string ✅ 打印机 IP 地址
port string ✅ 打印机端口,常用 9100;传空字符串时默认 9100
callback (result: number) => void ✅ 0 成功,-1 失败

Android 和 iOS 都支持。连接成功后,后续 printAreaSize、text、barcode、qrCode、print 等打印接口与蓝牙方式完全一致。

connectWifi('192.168.1.100', '9100', (result) => {
  if (result === 0) {
    printAreaSize({ height: 60 * 8, qty: 1 })
    pageWidth(60 * 8)
    text({ x: 10, y: 10, font: '16', content: 'Wi-Fi 打印测试' })
    print()
  }
})

iOS 首次连接局域网内的打印机时,系统会弹出“本地网络”权限授权框;插件已配置 NSLocalNetworkUsageDescription。
Android 已声明 INTERNET 权限。
Android 端已关闭厂商 SDK 的 Wi-Fi 握手检测,避免部分打印机不回握手包时被误判为连接失败。若仍失败,请检查 IP、端口 9100 是否可达,以及路由器是否开启了 AP 隔离;也可过滤 logcat 的 WifiPortManager 查看 SDK 返回码。


🧾 打印机设置

7. 打印机自检

selfTest(): void

执行打印机自检页,无参数。


8. 设置打印区域高度

printAreaSize(p: AreaParam): void
参数名 类型 必填 说明
height number ✅ 标签最大高度(点)
qty number ✅ 打印的标签数量(最大值 1024)
offset string ❌ 整体横向偏移,默认 0

9. 设置标签宽度

pageWidth(width: number): void
参数名 类型 必填 说明
width number ✅ 标签宽度(单位:点)

10. 标签定位

form(): void

说明: 在调用 print() 前使用,仅在标签模式下有效。


11. 执行打印

print(): void

说明: 执行打印缓存区的内容。


12. 设置对齐方式

setAlign(p: AlignParam): void
参数名 类型 必填 说明
p "LEFT" | "CENTER" | "RIGHT" ✅ 对齐方式

13. 设置打印浓度

setContrast(p: number): void
参数名 类型 必填 说明
p number ✅ 打印浓度:0=默认,1=中,2=深,3=非常深

14. 设置打印速度

setSpeed(p: number): void
参数名 类型 必填 说明
p number ✅ 打印速度 0~5,数值越大越快

15. 设置字体放大倍数

setMag(p: MagParam): void
字段 类型 必填 说明
width number ✅ 字体宽度放大倍数(1~16)
height number ✅ 字体高度放大倍数(1~16)

16. 设置字体加粗

setBold(p: number): void
参数名 类型 必填 说明
p number ✅ 加粗系数 0~5,0 取消加粗

🖨 打印内容

17. 打印文本

text(p: TextParam): void
字段 类型 必填 说明
x number ✅ 起始横坐标(点)
y number ✅ 起始纵坐标(点)
font string ✅ 字体名称
content string ✅ 打印内容
rotation '0' '90' '180'

18. 打印图片

image(p: ImageParam): void
字段 类型 必填 说明
x number ✅ 起始横坐标
y number ✅ 起始纵坐标
base64 string ✅ 图片 Base64 数据
algorithm 'Threshold' |'DiffusionDithering' | 'AggregateDithering' ❌ 图片算法. 默认二值算法(Threshold)
compressType number ❌ 压缩类型 0=不压缩 1=整体 2=分包

19. 打印条码

barcode(p: BarcodeParam): void
字段 类型 必填 说明
x number ✅ 起始横坐标
y number ✅ 起始纵坐标
width number ✅ 窄条宽度
height number ✅ 条码高度
content string ✅ 条码内容
ratio string ✅ 宽条窄条比例
vertical boolean ❌ 是否纵向打印
type BarcodeType ❌ 条码类型(默认 128)
undertext boolean ❌ 是否显示下方文字
number string ❌ 字体类型(仅 undertext=true 有效)
size string ❌ 字体大小
offset string ❌ 条码与文字距离

20. 打印二维码

qrCode(p: QrcodeParam): void
字段 类型 必填 说明
x number ✅ 起始横坐标
y number ✅ 起始纵坐标
content string ✅ 二维码内容
vertical boolean ❌ 是否纵向打印
M string ❌ QR 类型(1=普通 2=扩展)
U string ❌ 模块单位大小(1~32,默认6)
errorLevel QrErrorLevel ❌ 纠错等级(L/M/Q/H,默认 M)

QrErrorLevel 可选值:'L' | 'M' | 'Q' | 'H',默认 M;容错能力从 L 到 H 逐步增强,相同内容生成的二维码也会变大。


21. 打印矩形/直线/反白框

box(p: BoxParam): void
line(p: BoxParam): void
inverseLine(p: BoxParam): void
字段 类型 必填 说明
x number ✅ 起点 X
y number ✅ 起点 Y
xend number ✅ 终点 X
yend number ✅ 终点 Y
thickness number ✅ 线条宽度

22.使用示例

connectBlue("XX:XX:XX:XX:XX:XX", (result) => {
  if (result === 0) {
    // 确保连接成功再进行后续操作
  } else {
      return;
  }
});

hPrinter.printAreaSize({
    height: 60 * 8,
    qty: 1
});
hPrinter.pageWidth(60 * 8)
hPrinter.text({
    x: 10,
    y: 10,
    font: '16',
    content: '小鸡炖蘑菇'
})
hPrinter.barcode({
    x: 150,
    y: 30,
    content: 'ABCDEFG',
    type: '128',
    width: 1,
    ratio: '1',
    height: 50,
});
hPrinter.qrCode({
    x: 10,
    y: 50,
    M: '2',
    U: '6',
    errorLevel: 'H',
    content: '123456'
})
hPrinter.image({
    x: 150,
    y: 120,
    base64: 'data:image/png;base64,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'
})

// hPrinter.form() // 标签纸需要加
hPrinter.print()

隐私、权限声明

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

安卓: <uses-permission android:name="android.permission.BLUETOOTH"/> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/> <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> <uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> iOS: <key>NSBluetoothAlwaysUsageDescription</key> <string>开启蓝牙</string> <key>NSBluetoothPeripheralUsageDescription</key> <string>蓝牙</string> <key>UIBackgroundModes</key> <array> <string>bluetooth-central</string> </array>

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

无

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

无