轻量级、高性能的 Taro 蓝牙打印库 · 支持热敏票据、标签打印,覆盖 8+ 平台
| 能力 |
说明 |
| 多平台适配 |
微信/支付宝/百度/字节跳动/QQ 小程序,H5 WebBluetooth,鸿蒙,React Native |
| 多协议驱动 |
ESC/POS(热敏)、TSPL/ZPL/CPCL(标签)、STAR 系列 |
| 链式调用 |
printer.text(...).feed().qr(...).cut().print(),IDE 自动补全 |
| TypeScript |
完整类型定义,无任何 any 暴露,无外部依赖 |
| 编码支持 |
GBK / GB2312 / Big5 / UTF-8 / EUC-KR / Shift-JIS / ISO-2022-JP |
| 能力 |
说明 |
| 图片打印 |
Floyd-Steinberg 抖动算法,6 种抖动模式,RGBA → 黑白位图 |
| 二维码/条码 |
原生指令支持 Code128/EAN/UPC/QR/PDF417 等 10+ 格式 |
| 模板引擎 |
loop 循环 / condition 条件 / border 边框 / table 表格,小票标签一键渲染 |
| 暂停/恢复/取消 |
完整的打印任务生命周期控制 |
| 打印预览 |
ESC/POS 命令实时渲染为 Canvas 图像,调试所见即所得 |
| 能力 |
说明 |
| 离线缓存 |
断网自动缓存,来网自动同步,零任务丢失 |
| 打印队列 |
优先级排序,失败自动重试,死链自动剔除 |
| 多打印机管理 |
MultiPrinterManager 多设备并发,支持负载均衡 |
| 打印历史 |
PrintHistory 完整记录,含耗时/字节数/成功率统计 |
| 定时重试 |
ScheduledRetryManager 指数退避,进程重启后自动恢复调度 |
| 定时调度 |
PrintScheduler 支持 cron 表达式/一次性/间隔重复任务 |
| 设备发现 |
DiscoveryService 增强型过滤、排序、RSSI 缓存 |
| 指标 |
值 |
| 包体积(gzip) |
~226 KB(含全部驱动,无外部依赖) |
| Tree-shaking |
✅ 支持,import { BluetoothPrinter } 即用 |
| 按需加载 |
✅ 编码表懒加载,未用到的字符集不进入产物 |
| 测试覆盖 |
✅ 648 个用例,CI 全链路通过 |
pnpm add taro-bluetooth-print
import { createBluetoothPrinter, DeviceManager, WebBluetoothAdapter } from 'taro-bluetooth-print';
async function print() {
// 1. 扫描设备
const manager = new DeviceManager();
await manager.startScan({ timeout: 10000 });
const devices = manager.getDiscoveredDevices();
if (devices.length === 0) {
console.log('未发现设备');
return;
}
// 2. 创建打印机实例(推荐方式)
const printer = createBluetoothPrinter({
adapter: new WebBluetoothAdapter()
});
await printer.connect(devices[0].deviceId);
// 3. 链式调用打印
await printer
.text('=== 欢迎光临 ===', 'GBK')
.feed()
.text('商品A x1 ¥10.00', 'GBK')
.text('商品B x2 ¥20.00', 'GBK')
.feed()
.text('------------------------')
.text('合计: ¥30.00', 'GBK')
.feed(2)
.qr('https://example.com', { size: 6 })
.feed(2)
.cut()
.print();
await printer.disconnect();
}
| 平台 |
适配器 |
状态 |
| 微信小程序 |
TaroAdapter |
✅ |
| H5 (Web Bluetooth) |
WebBluetoothAdapter |
✅ |
| 支付宝小程序 |
AlipayAdapter |
✅ |
| 百度小程序 |
BaiduAdapter |
✅ |
| 字节跳动小程序 |
ByteDanceAdapter |
✅ |
| QQ 小程序 |
QQAdapter |
✅ |
| 鸿蒙 HarmonyOS |
TaroAdapter |
✅ |
| React Native |
ReactNativeAdapter |
✅ |
| 驱动 |
协议 |
典型品牌 |
EscPos |
ESC/POS |
佳博、芯烨、商米、汉印 |
TsplDriver |
TSPL |
TSC ME240、TA210、TTP-244 |
ZplDriver |
ZPL |
Zebra ZD420、GT800、ZM400 |
CpclDriver |
CPCL |
HP IR3222、霍尼韦尔移动机 |
StarPrinter |
STAR |
STAR TSP100、TSP700、TSP800 |
GPrinterDriver |
自定义 |
佳博 GP-5890X 系列 |
XprinterDriver |
ESC/POS |
芯烨 XP-58 系列 |
SprtDriver |
ESC/POS |
思普瑞特系列 |
const printer = createBluetoothPrinter();
// 传输参数
printer.setOptions({
chunkSize: 20, // 分片大小 byte(默认 20)
delay: 20, // 分片间隔 ms(默认 20)
retries: 3, // 写入失败重试次数(默认 3)
});
// 事件监听
printer.on('progress', ({ sent, total }) => {
console.log(`进度: ${(sent / total * 100).toFixed(1)}%`);
});
printer.on('error', (error) => {
// error 是 BluetoothPrintError 的实例
console.error('错误:', error.code, error.message);
});
printer.on('print-complete', () => {
console.log('打印完成');
});
import {
BluetoothPrintError,
ConnectionError,
PrintJobError,
CommandBuildError,
ErrorCode
} from 'taro-bluetooth-print';
// 统一错误基类
try {
await printer.print();
} catch (err) {
if (err instanceof BluetoothPrintError) {
console.log(err.code, err.message);
}
}
// 专用错误类型(推荐用于精确处理)
try {
await printer.connect(deviceId);
} catch (err) {
if (ConnectionError.isConnectionError(err)) {
// 连接失败:重试或提示用户
console.log('连接错误:', err.message);
}
}
try {
// ... 打印操作
} catch (err) {
if (PrintJobError.isPrintJobError(err)) {
// 打印任务失败:重新排队
console.log('任务错误:', err.message);
}
}
┌─────────────────────────────────────────┐
│ PrinterFactory (createPrinter) │
│ createBluetoothPrinter · createWebBluetooth │
└────────────────────┬────────────────────┘
▼
┌─────────────────────────────────────────┐
│ BluetoothPrinter (Core) │
│ text() feed() qr() cut() image() print()│
└──────────────┬──────────────────────────┘
│
┌─────────┼─────────┐
▼ ▼
┌─────────┐ ┌──────────┐
│ Drivers │ │ Adapters │
│ EscPos │ │ TaroAdapter│
│ Tspl │ │ WebBluetooth│
│ Zpl │ │ ReactNative │
└────┬────┘ └─────┬────┘
└──────────┬──────────┘
▼
┌──────────────────────────────────────┐
│ Services │
│ PrintJob · Cache · Queue · History │
│ Statistics · Scheduler · Batch │
└──────────────────────────────────────┘
git clone https://github.com/Agions/taro-bluetooth-print.git
cd taro-bluetooth-print
pnpm install
pnpm test # 测试(648 用例)
pnpm lint # ESLint + Prettier
pnpm type-check # TypeScript 检查
pnpm build # 构建产物
pnpm docs:dev # 本地文档
MIT · Copyright © 2024-present Agions