更新记录

1.0.3（2026-09-06）

• 优化;

1.0.2（2026-09-03）

• demo;

1.0.1（2026-09-03）

• demo;

平台兼容性

uni-app(5.25)

uni-app x(5.25)

其他

xl-qqPrinter

以下示例中的 qqPrinter 为插件导入后的接口对象。

import * as qqPrinter from '@/uni_modules/xl-qqPrinter'

基础流程

qqPrinter.onDisconnect(() => {
  console.log('设备已断开')
})

qqPrinter.startScan({
  duration: 15000,
  onScanResult: (device) => {
    console.log('发现设备', device)
  }
})

qqPrinter.connect({
  deviceId: deviceId,
  onConnectSuccess: (id) => {
    console.log('连接成功', id)
  },
  onConnectFail: (message) => {
    console.error('连接失败', message)
  }
})

qqPrinter.preparePrint((code, result) => {
  if (code === 'OK' && (result === 'ALL_READY' || result === 'LOW_POWER')) {
    qqPrinter.print({
      base64: imageBase64,
      widthMm: 50,
      heightMm: 30,
      density: 13,
      count: 1,
      paperType: 'Continuous',
      walkStep: 100
    })
  }
})

接口说明

onDisconnect

监听设备断开事件。

qqPrinter.onDisconnect(callback: () => void): void

onPrinterMessage

监听打印机主动上报的消息。

qqPrinter.onPrinterMessage((event) => {
  console.log(event.message, event.instruction, event.content, event.otherMsg)
})

event 字段：

startScan

开始扫描打印机。

qqPrinter.startScan({
  duration?: number,
  onScanResult?: (device) => void
}): void

• duration：扫描时长，单位为毫秒，默认值为 15000。
• onScanResult：发现设备时触发。

扫描结果字段：

stopScan

停止扫描。

qqPrinter.stopScan(): void

connect

连接扫描结果中的设备。

qqPrinter.connect({
  deviceId: string,
  onConnectSuccess?: (deviceId: string) => void,
  onConnectFail?: (message: string) => void
}): void

disconnect

断开当前设备连接。

qqPrinter.disconnect(): void

preparePrint

打印前检查设备状态。

qqPrinter.preparePrint((code, result) => {
  console.log(code, result)
})

• code：请求状态，例如 OK、TIMEOUT、BUSY、NOT_CONNECTED。
• result：设备状态，例如 ALL_READY、LOW_POWER、NO_PAPER、DEVICE_OPEN、TOO_HOT；请求失败时可能为 null。

查询设备信息

查询接口均应在设备连接后调用，回调第一个参数为请求状态，第二个参数为查询结果；请求失败时结果可能为 null。

qqPrinter.getBattery((code, battery) => {
  // battery：电量百分比
})

qqPrinter.getFirmwareVersion((code, version) => {
  // version：固件版本
})

qqPrinter.getSnCode((code, sn) => {
  // sn：打印机序列号
})

// getSNNumber 与 getSnCode 等价
qqPrinter.getSNNumber((code, sn) => {})

print

提交打印任务。

qqPrinter.print(options, callback?)

options 参数：

paperType 可选值：

打印回调参数：

qqPrinter.print(options, (result) => {
  console.log(result.code, result.message, result.currentIndex, result.totalCount)
})

cancelPrint

取消当前正在进行的打印任务。没有正在打印时调用不会产生影响。

qqPrinter.cancelPrint(): void