更新记录

1.0.0（2026-07-05）

适配宥彩usb小票打印机

平台兼容性

uni-app(3.7.13)

其他

使用方法

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

1. 适用范围

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

2. 放置位置

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

3. 导入方式

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

4. 基本调用流程

推荐的调用顺序如下：

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

5. 完整示例

import {
  listUsbDevices,
  connectUsb,
  disconnect,
  isConnected,
  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",
  ]);

  uni.showToast({
    title: 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

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

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 中每个字符串都会按一行打印
• 当前示例是纯文本打印，不包含图片、二维码、条码
• 插件内部依赖厂商 PosPrinterSdk_1.2.2.jar
• 发布到插件市场前，请确认第三方 SDK 的授权与再分发许可

9. 常见问题

找不到打印机

请检查：

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

连接失败

请尝试：

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

打印失败

请检查：

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