更新记录

1.0.4（2026-01-09）

• improve;

1.0.3（2026-01-05）

• fix iOS;

1.0.2（2026-01-05）

• fix;

平台兼容性

uni-app(4.87)

uni-app x(4.87)

欢迎使用 xl-hmT300 插件

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

本文档详细介绍蓝牙打印 SDK 的 TypeScript 接口定义及说明，适用于调用蓝牙打印机进行标签打印、二维码、条码、图像及文本输出等操作。

一、基本概念

打印流程

一次完整的标签打印流程如下：

1. start() —— 开始一张标签
2. 设置打印参数（宽度、高度等）
3. 添加打印内容（文字 / 条码 / 二维码 / 图片等）
4. end() —— 结束标签并立即打印

⚠️ 注意：未调用 end() 不会真正打印。

二、基础 API

1. 打印自检页

selfTest();

用于检测打印机是否工作正常。

2. 标签开始 / 结束

start();
end();

• start()：开始一张新标签
• end()：结束标签并打印

3. 设置标签尺寸

setPrintWidth(width: number);
setPrintHeight(height: number);

• 单位：dot（点）
• 常见 1mm ≈ 8dot（具体以打印机 DPI 为准）

示例：

setPrintWidth(800);
setPrintHeight(600);

三、打印内容接口

1. 打印文字 text

text(p: TextParam);

TextParam 参数说明

示例：

text({
  x: 20,
  y: 40,
  type: '7',
  size: '3',
  content: '测试文字'
});

2. 打印条码 barcode

barcode(p: BarcodeParam);

BarcodeParam 参数说明

支持条码类型：

• 128
• EAN13
• EAN8
• UPCE
• 39
• 93

示例：

barcode({
  x: 30,
  y: 100,
  ratio: 2,
  height: 120,
  content: '1234567890',
  type: '128',
  readable: true
});

3. 打印二维码 qrCode

qrCode(p: QrcodeParam);

QrcodeParam 参数说明

示例：

qrCode({
  x: 400,
  y: 50,
  size: 6,
  content: 'https://example.com'
});

4. 打印图片 image

image(p: ImageParam);

ImageParam 参数说明

图片算法：

• Threshold：黑白二值（默认）
• Dithering：抖动算法，灰度更细腻

示例：

image({
  x: 0,
  y: 0,
  base64: base64Image,
  algorithm: 'Dithering'
});

5. 自定义指令 customData

customData(p: string);

用于直接下发打印机原生指令（如 ZPL / CPCL / TSPL），需要打印机支持。

示例：

customData('^XA^FO50,50^ADN,36,20^FDHELLO^FS^XZ');

四、类型说明

旋转角度 Rotation

export type Rotation = 0 | 90 | 180 | 270;

蓝牙设备 HBlueDevice

export type HBlueDevice = {
  deviceId: string;
  name: string;
  paired?: boolean; // Android only
};

连接状态 ConnectState

export type ConnectState = 'connectSuccess' | 'connectFail' | 'disconnect';

五、完整示例

start();
setPrintWidth(800);
setPrintHeight(600);

text({
  x: 20,
  y: 30,
  type: '7',
  size: '4',
  content: '商品标签'
});

barcode({
  x: 20,
  y: 120,
  ratio: 2,
  height: 120,
  content: '6923450657713'
});

qrCode({
  x: 450,
  y: 120,
  size: 5,
  content: 'SN:202401010001'
});

end();

六、注意事项

• 所有坐标单位均为 dot
• 中文文字需使用 type = '7'
• 图片 Base64 不要包含 data:image/png;base64, 头
• 标签内容超出打印区域将被裁剪

七、常见问题

1. 打印不生效？

• 是否调用了 end()
• 是否已成功连接打印机

2. 图片打印模糊？

• 尝试使用 Dithering 算法
• 确保图片分辨率与打印尺寸匹配

如需扩展功能或适配其他指令集，请联系 SDK 提供方。