更新记录

1.0.0（2026-03-20）

• 初始化项目结构
• 实现基础打印能力

平台兼容性

uni-app(4.87)

uni-app x(4.87)

XLPrinter 多协议打印插件（UTS版）

🚀 一套 API 搞定所有打印机（ESC/POS / TSPL / CPCL / ZPL）

📦 插件简介

XLPrinter 是基于 UTS 开发的高性能打印插件，专为 uni-app x 打造。 支持蓝牙、USB 多连接方式，兼容主流打印指令协议，通过 JSON 数据驱动，实现统一、高效、易扩展的打印能力。

适用于小票打印、标签打印、面单打印等多种业务场景。

✨ 核心特性

• 🔥 多协议支持：ESC/POS / TSPL / CPCL / ZPL
• 🔌 多连接方式：蓝牙 / USB
• ⚡ UTS 原生实现（性能更强，无桥接损耗）
• 🧩 JSON 驱动打印（结构统一，易维护）

• 🖨️ 支持内容类型：

  • 文本
  • 图片
  • 条码
  • 二维码

• 📦 兼容主流打印机品牌：

  • 芯烨（XPrinter）
  • 佳博（Gprinter）
  • 芝柯（Zicox）
  • 商米（Sunmi）
  • 斑马（Zebra）
• 🧱 高扩展性（支持自定义指令封装）

🎯 适用场景

• 🧾 餐饮小票打印
• 🏪 零售收银打印
• 🏷️ 标签打印（仓储 / 物流）
• 📦 快递面单打印
• 🏭 工业打印

⚡ 快速开始

1️⃣ 创建实例

const printer = new XLPrinter()

2️⃣ 扫描蓝牙设备

printer.scanBlue(device => {
    console.log('发现设备:', device)
})

3️⃣ 连接设备

printer.connect(device.deviceId, 'blue')

4️⃣ 发送打印

printer.writeData(res => {
    console.log('打印结果:', res)
})

📚 API 文档

🔹 1. 监听事件

onBlueStateChange(callback)

监听蓝牙状态变化

printer.onBlueStateChange((state) => {
    console.log('蓝牙状态:', state)
})

onConnectSateChange(callback)

监听设备连接状态

printer.onConnectSateChange((res) => {
    console.log('连接状态:', res)
})

onDataReceive(callback)

监听设备数据回传

printer.onDataReceive((data) => {
    console.log('设备返回数据:', data)
})

onUsbAttached(callback)

监听 USB 插入

printer.onUsbAttached((device) => {
    console.log('USB设备:', device)
})

🔹 2. 设备管理

getUsbDevices()

获取当前 USB 设备列表

const list = printer.getUsbDevices()

scanBlue(callback)

扫描蓝牙设备

printer.scanBlue(device => {
    console.log(device.name)
})

stopScanBlue()

停止扫描蓝牙

printer.stopScanBlue()

🔹 3. 连接控制

connect(info, type)

连接设备

printer.connect(deviceId, 'blue')

disconnect()

断开连接

printer.disconnect()

isConnect()

是否已连接

if (printer.isConnect()) {
    console.log('已连接')
}

🔹 4. 数据发送

writeData(callback?)

发送打印数据

printer.writeData(res => {
    if (res.complete) {
        console.log('发送成功')
    } else {
        console.log('发送失败:', res.msg)
    }
})

🧩 数据结构

GBlueDevice（蓝牙设备）

{
    deviceId: string
    name: string
    paired?: boolean
}

GUsbDevice（USB设备）

{
    deviceName: string
    deviceId: string
    productName: string
    productId: string
    vendorId: string
    manufacturerName: string
}

ConnectBack（连接回调）

{
    state: ConnectState
    type: ConnectType
    info: string
    mseeage?: string
}

Gwrite（写入结果）

{
    complete: boolean
    msg?: string
}

🧠 使用建议

• ✔️ 打印前先判断 isConnect()
• ✔️ 蓝牙设备建议先配对
• ✔️ 大数据建议分包发送
• ✔️ 不同协议建议模块化封装

🆚 竞品优势

📞 技术支持

如有问题欢迎进入交流群交流