更新记录

1.0.0（2026-08-02）

首次发行

平台兼容性

uni-app(3.7.11)

其他

使用方法

这个文件专门说明 dlq-ucolor 插件的接入和调用方式。

1. 适用范围

• 仅支持 uni-app 的 Android App
• 当前能力用于 USB 小票打印
• 不支持 iOS、H5、各类小程序

2. 放置位置

将插件放到项目的 uni_modules 目录下。 uni_modules/dlq-ucolor

3. 导入方式

import {
  listUsbDevices,
  connectUsb,
  disconnect,
  isConnected,
  printQrCode,
  printQrImage,
  printTextReceipt,
} from "@/uni_modules/dlq-ucolor";

4. 基本调用流程

推荐的调用顺序如下：

1. 先获取 USB 设备列表
2. 选择一个设备并连接
3. 判断是否连接成功
4. 调用打印方法输出小票
5. 打印完成后按需要断开连接

5. 完整示例

import {
  listUsbDevices,
  connectUsb,
  disconnect,
  isConnected,
  printQrCode,
  printQrImage,
  printTextReceipt,
} from "@/uni_modules/dlq-ucolor";

export function testPrint() {
  const devices = listUsbDevices();

  if (!devices.length) {
    uni.showToast({
      title: "未找到 USB 打印机",
      icon: "none",
    });
    return;
  }

  const connectResult = connectUsb(devices[0]);

  if (!connectResult.success) {
    uni.showToast({
      title: connectResult.message || "连接失败",
      icon: "none",
    });
    return;
  }

  const result = printTextReceipt("收银小票", "欢迎光临", [
    "商品A x1  10.00",
    "商品B x2  36.00",
    "合计: 46.00",
  ]);

  const qrResult = printQrCode("https://example.com/order/123456");

  uni.showToast({
    title: qrResult.message || result.message || (result.success ? "打印成功" : "打印失败"),
    icon: "none",
  });
}

6. 返回值说明

连接、断开、打印接口都返回：

type PrinterConnectResult = {
  success: boolean;
  message?: string;
};

字段说明：

• success：是否成功
• message：原生侧返回的提示信息

7. 可用接口

listUsbDevices(): string[]

获取当前可识别的 USB 打印设备名称列表。

connectUsb(deviceName: string): PrinterConnectResult

连接指定设备。

disconnect(): PrinterConnectResult

断开当前连接。

isConnected(): boolean

判断当前是否已连接打印机。

printQrCode(content: string): PrinterConnectResult

打印居中的二维码：

• content：二维码内容，建议传订单链接、核销链接或支付链接
• 内容为空会返回失败
• 内容过长会返回失败

printQrCode("https://example.com/order/123456");

printQrImage(imagePath: string): PrinterConnectResult

打印已有二维码图片：

• imagePath：项目内 static 图片路径、本地图片路径、file:// 路径或 data:image/...;base64,...
• 推荐传黑白、边距充足的 PNG/JPG 二维码图片
• 图片会按 58mm 热敏纸常见宽度自动缩放到 384 点以内

const result = printQrImage("/static/order-qrcode.png");

uni.showToast({
  title: result.message || (result.success ? "打印成功" : "打印失败"),
  icon: result.success ? "success" : "none",
});

printTextReceipt(title: string, subtitle: string, lines: string[]): PrinterConnectResult

打印文本小票：

• title：标题
• subtitle：副标题
• lines：小票正文，每一项对应一行

const buildLines = () => {
  const lines: string[] = [""];
  lines.push("谢谢惠顾，欢迎下次光临");
  lines.push("谢谢惠顾，欢迎下次光临");
  return lines;
};

8. 使用注意

• 打印前必须先调用 connectUsb
• lines 中每个字符串都会按一行打印
• 文本小票接口不包含图片、条码；二维码内容请调用 printQrCode，二维码图片请调用 printQrImage
• 二维码通过热敏打印机 ESC/POS 指令生成，不依赖额外二维码图片库
• 二维码图片通过热敏打印机 ESC/POS 栅格图片指令打印
• 插件内部依赖厂商 PosPrinterSdk_1.2.2.jar
• 发布到插件市场前，请确认第三方 SDK 的授权与再分发许可

9. 常见问题

找不到打印机

请检查：

• 设备是否已通过 USB 正常连接
• 打印机是否通电
• Android 设备是否支持 USB Host

连接失败

请尝试：

• 重新插拔 USB 设备
• 重新获取设备列表后再次连接
• 关闭占用打印机的其他程序

打印失败

请检查：

• 是否已成功连接打印机
• 设备名称是否正确
• 打印机纸张是否正常