🖨️ Taro Bluetooth Print

轻量级、高性能的 Taro 跨端蓝牙打印库 — 覆盖 7 大平台、8 种打印协议，开箱即用

✨ 特性总览

📡 基础能力

| 能力 | 说明 | |:-----|:-----| | 多平台适配 | 微信 / 支付宝 / 百度 / 字节跳动 / QQ 小程序，H5 WebBluetooth，React Native | | 多协议驱动 | ESC/POS（热敏）、TSPL / ZPL / CPCL（标签）、STAR / 佳博 / 芯烨 / 思普瑞特 | | 链式调用 API | 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 → 黑白位图自适应转换，ESC/POS/ZPL/TSPL/STAR 全驱动支持 | | ZPL 图像编码 | ZplDriver.image() — ^GFA 命令，位图 → 十六进制编码，支持 ZD420 等 Zebra 标签机 | | CPCL Logo 下载 | CpclDriver.downloadLogo() — CG 压缩图形命令，宏定义存储，支持 HP 等移动打印机 | | 二维码 / 条码 | 原生指令支持 Code128 / EAN / UPC / QR / PDF417 等 10+ 格式 | | 模板引擎 | 支持 loop 循环 / condition 条件 / border 边框 / table 表格，小票标签一键渲染 | | 任务生命周期 | 完整的打印任务暂停 / 恢复 / 取消控制 | | 打印预览 | ESC/POS 命令实时渲染为 Canvas 图像，调试所见即所得 |

⚙️ 运维管理

| 能力 | 说明 | |:-----|:-----| | 离线缓存 | 断网自动缓存，恢复网络自动同步，零任务丢失 | | 打印队列 | 优先级排序、失败自动重试、死链自动剔除 | | 多打印机管理 | MultiPrinterManager 多设备并发，支持负载均衡 | | 打印历史 | PrintHistory 完整记录，含耗时 / 字节数 / 成功率统计 | | 定时重试 | ScheduledRetryManager 指数退避策略，进程重启后自动恢复调度 | | 定时调度 | PrintScheduler 支持 cron 表达式 / 一次性 / 间隔重复任务 | | 设备发现 | DiscoveryService 增强型过滤、排序、RSSI 信号缓存 | | 插件系统 | Hook-based 插件管理器，支持 beforePrint/afterPrint 等钩子 |

📦 安装

# npm
npm install taro-bluetooth-print

# pnpm（推荐）
pnpm add taro-bluetooth-print

# yarn
yarn add taro-bluetooth-print

前置依赖：项目需安装 @tarojs/taro ^3.6.22 及以上版本。

🚀 快速开始

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

async function printReceipt() {
  // ① 扫描蓝牙设备
  const manager = new DeviceManager();
  await manager.startScan({ timeout: 10000 });
  const devices = manager.getDiscoveredDevices();

  if (devices.length === 0) {
    console.warn('未发现蓝牙设备');
    return;
  }

  // ② 创建打印机实例并连接
  const printer = createBluetoothPrinter({
    adapter: new WebBluetoothAdapter()
  });

  await printer.connect(devices[0].deviceId);

  // ③ 链式调用 — 构建并打印小票
  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 | ✅ | | 支付宝小程序 | AlipayAdapter | ✅ | | 百度小程序 | BaiduAdapter | ✅ | | 字节跳动小程序 | ByteDanceAdapter | ✅ | | QQ 小程序 | QQAdapter | ✅ | | H5 (Web Bluetooth) | WebBluetoothAdapter | ✅ | | React Native | ReactNativeAdapter | ✅ |

💡 提示：鸿蒙 HarmonyOS 可通过 TaroAdapter 适配使用。

🖨️ 打印机驱动

| 驱动 | 协议 | 典型品牌 / 型号 | 功能状态 | |:-----|:-----|:---------------|:--------| | EscPos | ESC/POS | 佳博、芯烨、商米、汉印 | ✅ 全功能 | | TsplDriver | TSPL | TSC ME240、TA210、TTP-244 | ✅ 全功能 | | ZplDriver | ZPL | Zebra ZD420、GT800、ZM400 | ✅ 含图像打印 (^GFA) | | CpclDriver | CPCL | HP IR3222、霍尼韦尔移动打印机 | ✅ 含 Logo 下载 (CG) | | 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) => {
  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.error(`[${err.code}] ${err.message}`);
  }
}

// 方式二：按错误类型精确处理（推荐）
try {
  await printer.connect(deviceId);
} catch (err) {
  if (ConnectionError.isConnectionError(err)) {
    // 连接失败 — 可提示用户重试
    console.warn('连接错误:', err.message);
  }
}

try {
  // ... 打印操作
} catch (err) {
  if (PrintJobError.isPrintJobError(err)) {
    // 打印任务失败 — 可重新加入队列
    console.warn('任务错误:', err.message);
  }
}

try {
  printer.text('测试', 'UNSUPPORTED_ENCODING');
} catch (err) {
  if (CommandBuildError.isCommandBuildError(err)) {
    // 指令构建失败 — 参数校验问题
    console.warn('指令错误:', err.message);
  }
}

🏗️ 架构概览

 ┌──────────────────────────────────────────────────┐
 │              PrinterFactory (工厂层)                │
 │   createBluetoothPrinter · createWebBluetooth     │
 └─────────────────────┬────────────────────────────┘
                       │
                       ▼
 ┌──────────────────────────────────────────────────┐
 │            BluetoothPrinter (核心层)              │
 │   text() · feed() · qr() · cut() · image()       │
 │   print() · setOptions() · on() / off()          │
 └──────────┬───────────────────────┬───────────────┘
            │                       │
   ┌────────▼────────┐     ┌───────▼────────┐
   │   Drivers (驱动) │     │  Adapters (适配) │
   │                 │     │                 │
   │  EscPos        │     │  TaroAdapter    │
   │  TsplDriver    │     │  WebBluetooth   │
   │  ZplDriver     │     │  ReactNative    │
   │  CpclDriver    │     │  AlipayAdapter  │
   │  StarPrinter   │     │  BaiduAdapter   │
   │  GPrinter      │     │  ByteDance      │
   │  Xprinter      │     │  QQAdapter      │
   │  SprtDriver    │     │                 │
   └────────┬────────┘     └───────┬────────┘
            │                       │
            └───────────┬───────────┘
                        ▼
 ┌──────────────────────────────────────────────────┐
 │              Services (服务层)                     │
 │                                                   │
 │  ConnectionManager · PrintJobManager             │
 │  CommandBuilder · PrintScheduler                 │
 │  PrintQueue · OfflineCache · PrintHistory        │
 │  PluginManager (Hook-based)                      │
 └──────────────────────────────────────────────────┘

📊 性能指标

| 指标 | 值 | |:-----|:---| | 包体积（gzip） | ~231 KB（含全部驱动，无外部依赖） | | Tree-shaking | ✅ 支持，按需引入 | | 编码懒加载 | ✅ 未用到的字符集不进入产物 | | 测试用例 | ✅ 1,102 个测试用例，全部通过 | | 代码重复率 | ✅ 0%（jscpd 检测） | | 类型安全 | ✅ 零 any 暴露，类型断言最小化 | | 架构模式 | Template Method (ChunkWriteStrategy)、EventEmitter 类型安全、Mixin 模式 | | 构建工具 | Vite + Vitest + TypeScript 严格模式 |

📂 示例项目

| 示例 | 路径 | |:-----|:-----| | 微信小程序 | examples/weapp | | H5 | examples/h5 | | 鸿蒙 HarmonyOS | examples/harmonyos | | React Native | examples/react-native |

📖 文档

| 文档 | 说明 | |:-----|:-----| | 快速开始 | 5 分钟入门教程 | | 功能特性 | 全部功能详解 | | 驱动支持 | ESC/POS、TSPL、ZPL 驱动说明 | | 核心概念 | 架构设计与核心概念 | | API 参考 | 完整 API 文档 | | 常见问题 | FAQ |

🛠️ 开发

# 克隆仓库
git clone https://github.com/Agions/taro-bluetooth-print.git
cd taro-bluetooth-print

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 代码检查
pnpm lint

# TypeScript 类型检查
pnpm type-check

# 构建产物
pnpm build

# 本地文档开发
pnpm docs:dev

📄 许可证

MIT · Copyright © 2024-present Agions