更新记录

1.0.0（2026-08-12）

easy-printer 是一款面向 uni-app (Vue3) 的跨端蓝牙小票打印插件，支持 App (iOS/Android)、微信小程序、H5 三端。提供完整的设备扫描、连接管理、ESC/POS 指令构建与打印能力，兼容市面上常见的 58mm / 80mm 热敏小票打印机。

平台兼容性

uni-app(3.8.1)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
-	-	-	-	-	-	-	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
-	-	-	-	-	-	-	-	-	-	-	-

uni-app x(3.8.1)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	-	-	-	-

easy-printer — 跨端蓝牙小票打印SDK

插件简介

easy-printer 是一款面向 uni-app (Vue3) 的跨端蓝牙小票打印插件，支持 App (iOS/Android)、微信小程序、H5 三端。提供完整的设备扫描、连接管理、ESC/POS 指令构建与打印能力，兼容市面上常见的 58mm / 80mm 热敏小票打印机。

兼容平台

平台	支持情况	说明
App (Android)	完全支持	需要蓝牙和位置权限
App (iOS)	完全支持	需要蓝牙权限声明
微信小程序	部分支持	需自行调用 wx API 连接
H5	部分支持	依赖 Web Bluetooth API (Chrome/Edge)

快速上手

安装

将 uni_modules/easy-printer 目录复制到项目的 uni_modules 文件夹下即可。

基本使用

import { usePrinter, PrintAlign } from '@/uni_modules/easy-printer'

const printer = usePrinter({ debug: true })

// 1. 扫描设备
const devices = await printer.scan()

// 2. 连接设备
const result = await printer.connect(devices[0].deviceId)

// 3. 打印文本
await printer.printText('Hello World!', {
  align: PrintAlign.CENTER,
  bold: true,
})

// 4. 打印条码
await printer.printBarcode('6923456789012', {
  height: 80,
  width: 3,
})

// 5. 打印二维码
await printer.printQRCode('https://ext.dcloud.net.cn')

// 6. 切纸
await printer.cut()

// 7. 断开连接
await printer.disconnect()

组合打印（推荐）

import { usePrinter } from '@/uni_modules/easy-printer'
import type { PrintTask } from '@/uni_modules/easy-printer'

const printer = usePrinter({ autoCut: true })

const tasks: PrintTask[] = [
  { text: '=== 收银小票 ===' },
  { blankLines: 1 },
  { text: '商品A    x2    ￥20.00' },
  { text: '商品B    x1    ￥15.00' },
  { line: true },
  { text: '合计: ￥35.00' },
  { qrcode: { content: 'https://example.com/pay' } },
  { blankLines: 2 },
  { cut: true },
]

await printer.printReceipt(tasks)

API 参考

工厂函数

函数	参数	返回值	说明
`usePrinter(config?)`	`PrinterConfig` (可选)	`Printer` 实例	创建打印机实例

PrinterConfig — 打印机配置

字段	类型	默认值	说明
`printWidth`	`number`	`384`	打印宽度(点数)，384=58mm
`timeout`	`number`	`5000`	操作超时时间(ms)
`debug`	`boolean`	`false`	是否输出调试日志
`autoCut`	`boolean`	`false`	组合打印后自动切纸
`feedLines`	`number`	`2`	打印后自动走纸行数
`encoding`	`string`	`'gbk'`	字符编码

Printer — 实例方法

蓝牙操作

方法	参数	返回值	说明
`scan(options?)`	`ScanOptions`	`Promise<BluetoothDevice[]>`	扫描蓝牙设备
`connect(deviceId)`	`string`	`Promise<PrinterResult>`	连接设备
`disconnect()`	—	`Promise<PrinterResult>`	断开连接
`isConnected()`	—	`boolean`	是否已连接
`connectionState`	—	`PrinterConnectionState`	当前连接状态

打印操作

方法	参数	返回值	说明
`printText(text, options?)`	`string, TextOptions?`	`Promise<PrinterResult>`	打印文本
`printBarcode(content, options?)`	`string, BarcodeOptions?`	`Promise<PrinterResult>`	打印条码
`printQRCode(content, options?)`	`string, QRCodeOptions?`	`Promise<PrinterResult>`	打印二维码
`printLine(char?, count?)`	`string, number`	`Promise<PrinterResult>`	打印分割线
`printTwoColumn(left, right, width?)`	`string, string, number`	`Promise<PrinterResult>`	左右两列布局
`printTable(data)`	`TableData`	`Promise<PrinterResult>`	打印表格
`printBlankLines(count?)`	`number`	`Promise<PrinterResult>`	打印空行
`printReceipt(tasks)`	`PrintTask[]`	`Promise<PrinterResult>`	组合打印收据
`cut(feedCut?)`	`boolean`	`Promise<PrinterResult>`	切纸
`openCashDrawer()`	—	`Promise<PrinterResult>`	打开钱箱
`beep()`	—	`Promise<PrinterResult>`	蜂鸣提示
`initPrinter()`	—	`Promise<PrinterResult>`	初始化打印机
`sendRawData(data)`	`ArrayBuffer`	`Promise<PrinterResult>`	直接发送指令

TextOptions — 文本打印选项

字段	类型	默认值	说明
`align`	`PrintAlign`	`LEFT`	对齐方式
`size`	`TextSize`	`NORMAL`	文字大小
`bold`	`boolean`	`false`	是否加粗
`underline`	`boolean`	`false`	是否下划线
`lineSpacing`	`number`	—	行间距(点数)

BarcodeOptions — 条码选项

字段	类型	默认值	说明
`type`	`BarcodeType`	`CODE128`	条码类型
`height`	`number`	`80`	条码高度(点数)
`width`	`number`	`3`	条码宽度(1-6)
`textVisible`	`boolean`	`true`	是否显示可读字符
`align`	`PrintAlign`	`CENTER`	对齐方式

QRCodeOptions — 二维码选项

字段	类型	默认值	说明
`moduleSize`	`number`	`6`	模块大小(1-16)
`errorLevel`	`'L'\\|'M'\\|'Q'\\|'H'`	`'M'`	纠错级别
`align`	`PrintAlign`	`CENTER`	对齐方式

ScanOptions — 扫描选项

字段	类型	默认值	说明
`timeout`	`number`	`10000`	扫描超时(ms)
`filterPrinters`	`boolean`	`true`	是否仅显示打印机
`nameFilter`	`string`	—	名称过滤关键词

枚举值

PrintAlign — 对齐方式

值	说明
`LEFT`	左对齐
`CENTER`	居中对齐
`RIGHT`	右对齐

TextSize — 文字大小

值	说明
`NORMAL`	正常大小
`DOUBLE_WIDTH`	倍宽
`DOUBLE_HEIGHT`	倍高
`DOUBLE`	倍宽倍高

BarcodeType — 条码类型

值	说明
`UPC_A`	UPC-A
`UPC_E`	UPC-E
`EAN13`	EAN-13
`EAN8`	EAN-8
`CODE39`	Code39
`ITF`	ITF
`CODE128`	Code128（推荐）
`CODE93`	Code93
`CODABAR`	Codabar

PrinterErrorCode — 错误码

码值	说明
`0`	正常
`1001`	未找到设备
`1002`	连接失败
`1003`	已连接
`1004`	未连接
`1005`	打印失败
`1006`	蓝牙不可用
`1007`	蓝牙未开启
`1008`	权限被拒绝
`1009`	操作超时
`1010`	平台不支持

打印结果结构

interface PrinterResult {
  success: boolean
  errorCode?: PrinterErrorCode
  errorMessage?: string
}

常见问题

Q: App 端扫描不到设备？

确保已在 manifest.json 中配置蓝牙权限，Android 还需开启位置服务。iOS 需要在 manifest.json 的 app-plus.distribute.ios.privacyDescription 中声明蓝牙使用说明。

Q: 部分打印机连接后打印无反应？

不同品牌打印机的服务 UUID 和特征 UUID 可能不同。插件已内置常见打印机的 UUID 列表，如果您的设备不在此列表，可通过 sendRawData() 方法在连接后自行发送指令。

Q: 微信小程序如何使用？

微信小程序平台需要自行调用 wx.createBLEConnection 等原生 API 建立连接。建立连接后，可使用 CommandBuilder 类生成 ESC/POS 指令，再通过 wx.writeBLECharacteristicValue 发送。

Q: H5 平台有什么限制？

H5 平台依赖 Web Bluetooth API，目前仅 Chrome / Edge 等 Chromium 内核浏览器支持，且需要 HTTPS 环境。

Q: 打印中文出现乱码？

请将 PrinterConfig.encoding 设置为 'gbk'。部分打印机仅支持 GBK 编码。

版本记录

v1.0.0

首个正式版本
支持蓝牙设备扫描与连接
支持文本、条码、二维码打印
支持 ESC/POS 指令构建
兼容 App / 微信小程序 / H5 三端

easy-printer — 跨端蓝牙小票打印 蓝牙打印 小票打印 ESC/POS 热敏打印 跨端