更新记录

1.0.2（2026-09-03）

• demo;

1.0.1（2026-09-03）

• demo;

1.0.0（2026-09-03）

• initialization;

平台兼容性

uni-app(5.25)

uni-app x(5.25)

xl-qqPrinter

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS

Android 打印

连接成功后，建议先调用 preparePrint 检查设备状态，再调用 print：

qqPrinter.preparePrint((code, result) => {
  // code: OK、NOT_CONNECTED、BUSY
  // result: ALL_READY、LOW_POWER、NO_PAPER、DEVICE_OPEN、TOO_HOT
  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
    })
  }
})

查询设备信息

连接成功后可查询电量、固件版本和打印机 SN。回调第一个参数是请求状态（OK、TIMEOUT、BUSY、NOT_CONNECTED 等），第二个参数是查询结果；请求失败时结果为 null。

qqPrinter.getBattery((code, battery) => {
  if (code === 'OK') console.log('电量（百分比）', battery)
})

qqPrinter.getFirmwareVersion((code, version) => {
  if (code === 'OK') console.log('固件版本', version)
})

qqPrinter.getSnCode((code, sn) => {
  if (code === 'OK') console.log('打印机 SN', sn)
})
// getSNNumber 是 getSnCode 的同义别名

Android 端由 YXQPrinter 原生查询接口返回结果；iOS 端通过 YxqLibrary 封装层转发查询指令（电量、固件版本、SN），插件侧不直接依赖 YXQPrinterSDK 模块。查询指令需要在打印机连接成功后调用，且同一时间只应发起一个查询。

base64 支持带 data:image/...;base64, 前缀的图片。插件会按 Demo 的 8 点/mm 规则将图片缩放到 widthMm × heightMm 后打印。

iOS 打印

iOS 端通过 YxqLibrary.framework 调用 YXQPrinterSDK.framework，对外接口与 Android 保持一致：

1. startScan({ duration, onScanResult }) 扫描，回调结果包含 name、deviceId 和 rssi（蓝牙信号强度，单位 dBm；未提供时为 null），deviceId 使用 CBPeripheral.identifier.UUIDString。
2. connect({ deviceId, onConnectSuccess, onConnectFail }) 只能连接本次扫描得到的设备；回调统一在主线程触发。
3. 连接成功后先调用 preparePrint，状态码与 Android 一致（ALL_READY、LOW_POWER、NO_PAPER、DEVICE_OPEN、TOO_HOT）。iOS 原生层通过 onPreparePrint 属性回调结果，不再把回调 block 作为 preparePrint 参数传递。P50 机型按官方 Demo 直接进入打印流程，其他机型使用 QueryStateBeforePrint 检查状态。
4. print 在原生层完成 Base64 解码和图片缩放（8 点/mm），连续纸的 walkStep 使用 SDK 的 extraPaperStep。

可通过 onPrinterMessage 监听打印机主动上报：

qqPrinter.onPrinterMessage((event) => {
  // event.message：缺纸、卡纸、过热、低电量、仓盖打开等
  // event.instruction：SDK 原始指令编号
  console.log(event.message, event.instruction, event.content)
})

真机打包必须同时携带 YxqLibrary.framework 和 YXQPrinterSDK.framework，且当前 SDK 只有 arm64 真机 slice；没有模拟器 slice 时请使用真机运行或向 SDK 提供方索取 XCFramework。iOS 工程还必须声明蓝牙用途描述（本插件已在 manifest.json 中配置）。