更新记录

2.2.0（2026-09-07）

• 安卓添加串口打印;
• zpl打印完善;
• 优化 iOS 打印;

2.1.3（2026-08-05）

• 优化文本打印;

2.1.2（2026-04-20）

• iOS文本打印增强;
• 提升iOS连接体验;

平台兼容性

uni-app(4.75)

uni-app x(4.75)

kaka-KPrinter

欢迎使用 KPrinter UTS 插件。此插件适用于蓝牙热敏打印机，同时支持 USB、串口和以太网通道，以下是说明及使用教程。

• 适用厂商：佳博、启锐、汉印 等主流打印机
• 支持的指令类型：TSPL/TSC、CPCL、ESC
• Android、iOS 额外支持：ZPL
• 支持平台：安卓、iOS、鸿蒙-开发中
• 单位换算：200dip：1mm = 8dot、300dip：1mm = 12dot（实际点数以打印机 DPI 为准）
• uni-app x / uvue demo 请见 kprinter-uvue demo

使用指南

• 蓝牙使用指南
• USB 使用指南
• 以太网使用指南
• TSPL 使用指南
• CPCL 使用指南
• ESC 使用指南

快速开始

导入插件

import * as KPrinter from '@/uni_modules/kaka-KPrinter';

基本调用流程

打印分为三步：连接打印机、构建指令、通过当前连接通道发送。

// 1. 连接设备，例如蓝牙
KPrinter.connect(deviceId);

// 2. 构建打印内容
KPrinter.escInitializePrinter();
KPrinter.escText('打印测试\n');

// 3. 通过蓝牙发送
KPrinter.writeData();

连接方式与发送函数：

每次发送完成后，当前指令缓存会被清空。下一次打印需要重新构建指令。

连接打印机

蓝牙

KPrinter.onBlueStateChange((isOn) => {
    console.log(isOn ? '蓝牙已开启' : '蓝牙已关闭');
});

KPrinter.onConnectStateChange({
    onSuccess: (device) => console.log('连接成功', device),
    onDisconnect: (device) => console.log('连接断开', device),
    onFail: (message) => console.error('连接失败', message)
});

KPrinter.startScan((device) => {
    console.log('发现设备', device.name, device.deviceId);
});

KPrinter.stopScan();
KPrinter.connect(deviceId);

const pairedDevices = KPrinter.getBondedDeviceList();
const connected = KPrinter.isConnect();

KPrinter.disconnect();

USB

KPrinter.onUSBConnectStateChange({
    usbDeviceAttached: (device) => console.log('发现USB设备', device),
    onSuccess: (device) => console.log('USB连接成功', device),
    onDisconnect: () => console.log('USB连接断开'),
    onFail: (message) => console.error('USB连接失败', message)
});

KPrinter.getUsbDeviceList((device) => {
    console.log(device.deviceName, device.vendorId, device.productId);
});

KPrinter.connectUSB(deviceName);
KPrinter.disConnectUSB();

USB 连接时，系统可能弹出设备访问授权，请允许后再打印。

以太网

KPrinter.onEthernetConnectStateChange({
    onSuccess: () => console.log('以太网连接成功'),
    onDisconnect: () => console.log('以太网连接断开'),
    onFail: (message) => console.error('以太网连接失败', message)
});

KPrinter.connectEthernet('192.168.1.100', '9100');
KPrinter.disConnectEthernet();

打印机常用 RAW 端口为 9100。IP 和端口应以打印机当前网络设置为准。

Android 串口

const ports = KPrinter.getSerialPortList();

KPrinter.onSerialConnectStateChange({
    onSuccess: (device) => console.log('串口连接成功', device),
    onDisconnect: () => console.log('串口连接断开'),
    onFail: (message) => console.error('串口连接失败', message)
});

KPrinter.connectSerial('/dev/ttyS0', 9600);
KPrinter.disConnectSerial();

常见串口节点包括 /dev/ttyS0、/dev/ttyUSB0、/dev/ttyACM0。波特率必须与打印机设置一致；自定义串口节点可直接传给 connectSerial()。

数据和写入回调

KPrinter.onWriteComplete((success) => {
    console.log(success ? '数据写入成功' : '数据写入失败');
});

KPrinter.onDataReceive((data) => console.log('蓝牙或USB数据', data));
KPrinter.onSerialDataReceive((data) => console.log('串口数据', data));
KPrinter.onEthernetDataReceive((data) => console.log('以太网数据', data));

写入成功表示数据已经通过当前通道发出，不等同于打印机已经完成打印。

TSPL/TSC 打印

典型调用顺序：设置纸张 → 清除缓存 → 添加内容 → 设置打印份数 → 发送。

KPrinter.tscSize({ width: 60, height: 40 }); // 单位：毫米
KPrinter.tscCls();
KPrinter.tscDensity(8);
KPrinter.tscDirection({ directionReverse: false, isMirror: false });

KPrinter.tscText({
    x: 30, y: 30,
    font: 'TSS24.BF2', rotation: 0,
    xScal: 1, yScal: 1,
    content: 'TSPL 打印测试'
});

KPrinter.tscBarCode({
    x: 30, y: 80,
    codeType: '128', height: 80,
    readable: true, content: '1234567890'
});

KPrinter.tscQRCode({
    x: 30, y: 200,
    cellWidth: 5, rotation: 0,
    content: 'https://example.com'
});

KPrinter.tscPrint(1);
KPrinter.writeData();

常用接口：

• tscSize()：设置标签尺寸，单位毫米
• tscCls()：清除标签绘制缓存
• tscText()、tscCustomText()、tscBlock()：文本和段落
• tscBar()、tscBox()、tscErase()、tscReverse()：图形和区域操作
• tscBarCode()、tscQRCode()：条码和二维码
• tscImage()、tscPDFBase64()：图片和 PDF 页面
• tscSpeed()、tscDensity()、tscDirection()、tscGap()：打印参数
• tscSelfTest()：打印自检页
• tscStringCommand()、tscBytesCommand()：追加原始指令

CPCL 打印

KPrinter.cpclSize({ width: 60 * 8, height: 40 * 8, copies: 1 });

KPrinter.cpclText({
    x: 20, y: 30,
    font: '4', xScal: 1, yScal: 1,
    rotation: 0, content: 'CPCL 打印测试'
});

KPrinter.cpclBarCode({
    x: 20, y: 80,
    width: 3, height: 80,
    vertical: false, codeType: '128',
    content: '1234567890'
});

KPrinter.cpclQRCode({
    x: 20, y: 200,
    cellWidth: 5, rotation: 0,
    content: 'https://example.com'
});

// 标签纸根据机型需要调用 cpclForm()
KPrinter.cpclPrint();
KPrinter.writeData();

常用接口：

• cpclSize()：设置纸张点数和打印份数
• cpclText()、cpclCustomText()：打印文本
• cpclLine()、cpclBox()、cpclInverseLine()：线条、边框和反白
• cpclBarCode()、cpclQRCode()、cpclQRCodeImage()：条码和二维码
• cpclImage()、cpclPDFBase64()：图片和 PDF 页面
• cpclJustification()：设置对齐方式
• cpclForm()、cpclPrint()：结束表单并打印
• cpclStringCommand()、cpclBytesCommand()：追加原始指令

ESC/POS 打印

KPrinter.escInitializePrinter();
KPrinter.escJustification('center');
KPrinter.escSetCharcterSize({ xScal: 2, yScal: 2 });
KPrinter.escText('ESC/POS 打印测试\n');

KPrinter.escSetCharcterSize({ xScal: 1, yScal: 1 });
KPrinter.escQRCode({ content: 'https://example.com', size: 5 });
KPrinter.escText('\n\n\n');
KPrinter.escCutPaper();
KPrinter.writeData();

常用接口：

• escInitializePrinter()：初始化打印机
• escText()、escCustomText()：打印文本
• escJustification()：设置左、中、右对齐
• escSetCharcterSize()、escTurnEmphasizedMode()：字号和加粗
• escImage()：打印 base64 图片
• escQRCode()、escBarCode()、escBarCodeImage()：二维码和条码
• escLineSpacing()、escNewLine()、escPrintAndFeedLines()：间距和走纸
• escCutPaper()、escSound()：切纸和蜂鸣器
• escTwoText58() 至 escFiveText80()：小票多列文本排版
• escStringCommand()、escBytesCommand()：追加原始指令

ZPL 打印

ZPL 在 Android 和 iOS 端均可使用，坐标、尺寸和字号统一使用打印机 dot。典型流程是开始标签、追加内容、结束标签后发送：

KPrinter.zplStart();
KPrinter.zplLabelWidth(640);
KPrinter.zplLabelLength(600);
KPrinter.zplText({ x: 30, y: 30, content: 'ZPL 测试', fontHeight: 40, fontWidth: 40 });
KPrinter.zplCode128({ x: 30, y: 120, content: '1234567890', height: 80, showText: true });
KPrinter.zplQRCode({ x: 30, y: 260, content: 'https://example.com', magnification: 5 });
KPrinter.zplPrint(1);
KPrinter.zplEnd();
KPrinter.writeData();

zplStringCommand() 和 zplBytesCommand() 可用于追加打印机支持的原始 ZPL。Android、iOS SDK 均可把 base64 图片转换为黑白 ZPL 点阵。 切纸和蜂鸣器需要打印机硬件支持。

ZPL 图片与参数说明

ZPL 坐标和尺寸均使用打印机 dot。典型调用顺序：zplStart() → 设置标签和内容 → zplPrint() → zplEnd() → 发送。

KPrinter.zplStart();
KPrinter.zplLabelWidth(640);
KPrinter.zplLabelLength(600);
KPrinter.zplLabelHome({ x: 0, y: 0 });

KPrinter.zplText({
    x: 30, y: 30,
    content: 'ZPL 打印测试',
    fontHeight: 40, fontWidth: 40
});

// 中文或打印机未内置中文字体时，使用位图文字
KPrinter.zplCustomText({
    x: 30, y: 85,
    content: '中文自定义文字',
    fontSize: 40
});

KPrinter.zplCode128({
    x: 30, y: 150,
    content: '1234567890',
    height: 80, showText: true
});

KPrinter.zplQRCode({
    x: 30, y: 290,
    content: 'https://example.com',
    magnification: 5
});

KPrinter.zplBox({ x: 20, y: 20, width: 580, height: 520, thickness: 2 });
KPrinter.zplPrint(1);
KPrinter.zplEnd();
KPrinter.writeData();

ZPL 图片

KPrinter.zplImage({
    x: 330,
    y: 230,
    base64Str: 'data:image/png;base64,...',
    width: 240,
    name: 'KPRINTER.GRF',
    xScale: 1,
    yScale: 1
});

base64Str 可以是纯 base64，也可以是 data:image/...;base64,...，SDK 会转换为黑白点阵；建议根据标签宽度设置 width，避免数据量过大。

ZPL 参数说明

ZPL 同样可以通过 USB、串口和以太网发送，只需把最后的 writeData() 替换为对应通道的发送函数。

图片和 PDF 参数

• 图片支持纯 base64 和包含 data URI 前缀的 base64 字符串。
• width 表示缩放后的目标宽度；不传时通常使用原图宽度。
• dithering 用于改善灰度图片转黑白后的效果。
• compress 需要打印机支持，一般可以不传。
• PDF 接口的 index 表示页码，默认打印第一页。

权限说明

Android

<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" />

Android 12 及以上应动态申请蓝牙扫描和连接权限。旧版本扫描蓝牙时可能还需要定位权限。

iOS

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要使用蓝牙连接打印机</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要使用蓝牙连接打印机</string>
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

常见问题

连接成功但没有打印

确认写入前已经构建指令，并调用了与当前连接方式匹配的发送函数。还应确认打印机当前指令模式与发送的 TSPL、CPCL、ESC 或 ZPL 一致。

中文乱码

中文打印取决于打印机代码页和字体支持。可以先打印自检页确认设置；需要自行控制编码时，使用对应协议的字节指令接口。

图片打印慢或超出标签

建议先缩小图片，或通过 width 设置目标宽度。标签坐标和图片宽度需要根据打印机 DPI 及实际纸张尺寸计算。

写入成功是否代表打印完成

不是。写入回调表示数据已经发送到连接通道，打印机是否完成走纸、切纸或出纸，需要结合设备状态和实际打印结果判断。