taro-bluetooth-print

🌐

七大平台适配

微信 / 支付宝 / 百度 / 字节跳动 / QQ 小程序、H5 WebBluetooth、React Native、鸿蒙 HarmonyOS——一套代码自动 dispatch 到正确适配层。

🖨️

八大协议驱动

ESC/POS、TSPL、ZPL、CPCL、STAR、GPrinter、Xprinter、SPRT 全场景覆盖：商米、汉印、TSC、Zebra、STAR 等主流品牌开箱即用。

⛓️

优雅链式 API

`printer.text(...).qr(...).cut().print()` 一气呵成。所有方法返回 `this`，IDE 严格模式自动补全，错误抛 `BluetoothPrintError`。

📝

模板引擎

`loop` 循环 / `condition` 条件 / `border` 边框 / `table` 表格——为复杂小票和标签布局提供 DSL 级抽象，一键渲染。

💾

离线缓存 + 智能重试

Base64 序列化 · LRU 驱逐 · 指数退避 · 进程重启自动恢复。打印任务 0 丢失保障。

📦

企业级运维栈

优先级队列 · Cron 调度 · 全链路统计 · 插件钩子系统——支撑高并发打印场景的可观测性与可扩展性。

⚡ 快速开始

仅需几行代码，即可完成跨端蓝牙打印：

bash

# 推荐使用 pnpm
pnpm add taro-bluetooth-print

typescript

import { createBluetoothPrinter, WebBluetoothAdapter } from 'taro-bluetooth-print';

// ① 创建打印机（自动 dispatch 当前平台适配器）
const printer = createBluetoothPrinter({
  adapter: new WebBluetoothAdapter(),
});

// ② 连接 BLE 设备
await printer.connect('device-id-xxx');

// ③ 链式 API 构建小票
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();

🏗️ 架构设计

一个清晰分层的 6 层架构 — 每一层只与相邻层耦合：

mermaid

flowchart TB
    subgraph User["👤 应用层"]
        App["应用代码<br/>(小票 / 标签)"]
    end
    subgraph Factory["🏭 Factory 层"]
        F["createBluetoothPrinter()<br/>PrinterFactory"]
    end
    subgraph Core["🎛️ Core 层"]
        BP["BluetoothPrinter<br/><i>(Facade)</i>"]
    end
    subgraph Services["⚙️ Service 层"]
        CM["ConnectionManager"]
        JM["PrintJobManager"]
        CB["CommandBuilder"]
        Queue["PrintQueue / OfflineCache<br/>PrintScheduler / PluginManager"]
    end
    subgraph Drivers["🖨️ Driver 层"]
        E1["EscPos"]
        E2["TsplDriver"]
        E3["ZplDriver"]
        E4["CpclDriver"]
        E5["StarPrinter / SPRT / ...<br/><i>(ISendCommand)</i>"]
    end
    subgraph Adapters["📡 Adapter 层"]
        A1["TaroAdapter (迷你程序)"]
        A2["WebBluetoothAdapter"]
        A3["ReactNativeAdapter"]
    end
    subgraph Errors["🛡️ Error 层"]
        ER["BluetoothPrintError<br/>+ Connection / PrintJob / CommandBuild"]
    end

    User --> Factory --> Core
    Core --> Services
    Services --> Drivers
    Services --> Adapters
    Core -.throws.-> Errors
    Services -.throws.-> Errors

💡 设计原则：依赖单向流动 · interface 抽象掉具体实现 · 插件 hook 横切所有层。

📋 平台 & 驱动矩阵

	ESC/POS	TSPL	ZPL	CPCL	STAR
微信小程序	✅	✅	✅	✅	✅
支付宝小程序	✅	✅	✅	✅	✅
百度小程序	✅	✅	✅	✅	✅
字节跳动小程序	✅	✅	✅	✅	✅
QQ 小程序	✅	✅	✅	✅	✅
H5（Web Bluetooth）	✅	✅	✅	✅	✅
React Native	✅	✅	✅	✅	✅
鸿蒙 HarmonyOS	✅	✅	✅	✅	✅

ESC/POS

TSPL

ZPL

CPCL

STAR

微信小程序

✅

支付宝小程序

✅

百度小程序

✅

字节跳动小程序

✅

QQ 小程序

✅

H5（Web Bluetooth）

✅

React Native

✅

鸿蒙 HarmonyOS

✅

全部驱动 = new EscPos() / new TsplDriver() / new ZplDriver() / new CpclDriver() / new StarPrinter()，全部在 drivers/index.ts 命名导出。

🌟 核心亮点

📦 极致轻量

main bundle ~89 KB / 25.5 KB gzip，GBK 表按需懒加载，零运行时依赖，tree-shaking 友好

💎 类型安全

TypeScript 严格模式 + 完整 I-prefix interface 契约

🧪 测试覆盖

1,436 个测试 71.5% 覆盖率（lines），jscpd 0 重复，零死代码

🧩 可组合

Plugin hook 系统 · 9 个生命周期钩子 · 类型化错误层次

🔌 多语言

GBK / GB2312 / Big5 / UTF-8 / EUC-KR / Shift-JIS / ISO-2022-JP

🎨 Floyd-Steinberg

6 种抖动算法 + 缩放/预处理/海报化，完美的图像转打印

🧭 下一步

我想...	跳转
5 分钟跑通第一个 Demo	→ 快速开始
弄清分层架构与核心概念	→ 核心概念
看完整 API 与示例	→ API 参考
找 1,000+ 台适配的打印机型号	→ 驱动支持
解决具体报错	→ 故障排查
看 FAQ	→ 常见问题

我想...

跳转

5 分钟跑通第一个 Demo

弄清分层架构与核心概念

看完整 API 与示例

找 1,000+ 台适配的打印机型号

解决具体报错