更新记录

1.0.0（2025-09-09）

第一版本打印

平台兼容性

uni-app

uni-app x

xiongdong-PrintDemo

插件简介

基于 UTS 开发的热敏小票打印封装，支持 Android 平台下的蓝牙、WiFi、USB 三种连接方式，并提供小票格式化打印、二维码/条形码打印、走纸/切纸、字体样式与对齐等常用能力。

• 支持平台: App-Android（iOS 暂为示例模板，未实现打印能力）
• 典型机型: 58mm/80mm 热敏票据打印机（具体指令/功能取决于机型与 SDK 能力）

安装与导入

1) 将本插件放入 uni_modules/xiongdong-PrintDemo 2) 直接在 Vue/TS 中导入 UTS API 使用（HBuilderX/uni-app 支持 *.uts 直接导入）

// 仅 Android 下可用的打印能力
import {...} as Print from '@/uni_modules/xiongdong-PrintDemo'

提示：如需在跨平台代码中安全调用，请自行判断运行平台再调用对应方法。

const isAndroid = uni.getSystemInfoSync().platform === 'android'

快速开始

• 蓝牙打印（已配对并知道目标打印机 MAC 地址）

  const { success, message } = await Print.btConnect('AA:BB:CC:DD:EE:FF')
  if (success) {
  await Print.btPrintText('Hello Thermal!\n')
  await Print.btPrintReceipt({
  shopName: '演示门店',
  orderNo: 'NO2025-0001',
  cashier: '张三',
  time: '2025-01-01 12:00:00',
  items: [ { name: '咖啡', qty: 1, price: 1200 } ],
  total: 1200, pay: 2000, change: 800,
  footer: '谢谢惠顾',
  qrContent: 'https://example.com/order/NO2025-0001'
  })
  } else {
  uni.showToast({ title: message, icon: 'none' })
  }

• WiFi 打印

  await Print.connectToWifiPrinter('192.168.1.123', 9100)
  await Print.wifiPrintText('WiFi 打印测试\n')
  await Print.wifiPrintQRCode('https://example.com', 6)
  await Print.wifiCutPaper(3)

• USB 打印（需要用户授权）

  const devices = Print.usbListDevices() // [{ id, vendorId, productId, name, hasPermission }]
  if (devices.length) {
  const d = devices[0]
  if (!d.hasPermission) {
  Print.usbRequestPermission(d.id) // 触发系统授权弹窗
  // 用户授权后再次尝试连接
  } else {
  await Print.connectToUsbPrinter(d.id)
  await Print.usbPrintText('USB 打印测试\n')
  await Print.usbCutPaper(3)
  }
  }

小票数据结构与样例

• 单位约定：价格与金额以「分」为单位传入（内部会格式化为元显示）。
• 建议 58mm 机型使用 32 列字符宽（已内置简单列对齐）。

const receipt = {
  shopName: '示例门店(58mm)',
  orderNo: 'NO2025-000123',
  cashier: '张三',
  time: '2025-01-01 10:00:00',
  items: [
    { name: '拿铁咖啡(大杯)', qty: 1, price: 2680 },
    { name: '曲奇饼干', qty: 2, price: 590 },
    { name: '可乐(听)', qty: 1, price: 450 }
  ],
  total: 2680 + 2 * 590 + 450,
  pay: 5000,
  change: 5000 - (2680 + 2 * 590 + 450),
  footer: '谢谢惠顾 欢迎下次光临',
  qrContent: 'https://example.com/order/NO2025-000123'
}

// 根据当前连接类型（优先 WiFi → USB → 蓝牙）打印
await Print.printSampleReceipt() // 内置示例；或调用对应的 *PrintReceipt(receipt)

API 列表（Android）

• 蓝牙

  • btConnect(mac: string): Promise<{success, message, device?}>
  • btDisconnect(): {success, message}
  • btPrintText(text: string): Promise<{success, message}>
  • btTestPrint(): Promise<{success, message}>
  • btIsConnected(): boolean
  • btGetCurrentDevice(): {name, address, type} | null
  • btPrintReceipt(receipt: any): Promise<{success, message, cutPaper?: boolean}>

• WiFi（9100 原生直连）

  • connectToWifiPrinter(ip: string, port = 9100): Promise<{success, message}>
  • disconnectWifiPrinter(): {success, message}
  • getWifiConnectionStatus(): {connected: boolean}
  • wifiPrintText(text: string): Promise<{success, message}>
  • wifiPrintQRCode(data: string, size = 6): Promise<{success, message}>
  • printWifiTestPage(): Promise<{success, message}>
  • isWifiActive(): boolean
  • getCurrentWifiInfo(): {ssid, bssid, ipAddress, signalStrength} | null
  • getDeviceIpAddress(): {success, ipAddress? , message?}
  • getWifiDebugInfo(): {success, ...}
  • wifiCutPaper(lines = 3): Promise<{success, message}>
  • wifiPrintReceipt(receipt: any): Promise<{success, message, cutPaper?: boolean}>

• USB

  • usbListDevices(): Array<{ id, vendorId, productId, name, hasPermission }>
  • usbRequestPermission(deviceId: number): {success, message}
  • connectToUsbPrinter(deviceId: number): Promise<{success, message, device?}>
  • disconnectUsbPrinter(): {success, message}
  • getUsbConnectionStatus(): {connected: boolean}
  • usbPrintText(text: string): Promise<{success, message}>
  • usbPrintQRCode(data: string, size = 6): Promise<{success, message}>
  • usbCutPaper(lines = 3): Promise<{success, message}>
  • usbPrintReceipt(receipt: any): Promise<{success, message, cutPaper?: boolean}>

• 通用（针对当前已连接的打印实例生效）

  • setFontStyle(bold=false, doubleHeight=false, doubleWidth=false): {success, message}
  • setTextAlign(align: number): {success, message} // 0=左、1=中、2=右
  • setFontScale(bold=false, heightScale=0, widthScale=0): {success, message} // 倍率 0/1/2
  • setLineHeight(height: number): {success, message}
  • lineFeed(lines: number): {success, message}
  • printBarcode(data: string, type: number): {success, message}
  • getPrinterStatus(): {success, message, status: number}
  • printSampleReceipt(): Promise<{success, message}>

使用建议与注意事项

• 不同打印机/固件对指令支持差异较大：二维码/切纸/字体放大等能力需机型支持。
• WiFi/USB 连接失败时请检查网络连通性、端口、线缆与授权状态。
• USB 首次连接需系统授权，授权后再调用连接；更换 USB 口可能需重新授权。
• 蓝牙需在系统设置中完成配对；确保蓝牙已开启且 MAC 地址有效。
• 小票列宽与字符集在不同机型上效果不同，可结合 setFontScale/setLineHeight 做适配。
• 建议将金额以「分」传入，避免浮点精度问题。

常见问题

• 切纸无效？部分 58mm 机型不带切刀或 SDK 不支持；可仅走纸。
• 二维码打印失败？请尝试调整 size 或检查机型是否支持当前签名；不影响文本打印。
• 如何判断当前连接？使用 getWifiConnectionStatus() / getUsbConnectionStatus() / btIsConnected()。

参考

• UTS 语法: https://uniapp.dcloud.net.cn/tutorial/syntax-uts.html
• UTS API 插件: https://uniapp.dcloud.net.cn/plugin/uts-plugin.html
• UTS 组件: https://uniapp.dcloud.net.cn/plugin/uts-component.html