{"id":45797012,"url":"https://github.com/agions/taro-bluetooth-print","last_synced_at":"2026-05-02T09:04:00.009Z","repository":{"id":347459440,"uuid":"1193707751","full_name":"Agions/taro-bluetooth-print","owner":"Agions","description":"A lightweight, high-performance Bluetooth printing library for Taro. Supports ESC/POS thermal receipt and TSPL/ZPL/CPCL label printers across WeChat, Alipay, QQ, Baidu \u0026 ByteDance mini-programs, H5 WebBluetooth, React Native and HarmonyOS.","archived":false,"fork":false,"pushed_at":"2026-04-20T11:58:57.000Z","size":2338,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T13:42:41.771Z","etag":null,"topics":["bluetooth","bluetooth-print","esc-pos","label-printer","mini-program","printer","printing","react-native","taro","thermal-printer","tspl","typescript","web-bluetooth","zpl"],"latest_commit_sha":null,"homepage":"https://agions.github.io/taro-bluetooth-print/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Agions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T13:54:38.000Z","updated_at":"2026-04-20T11:59:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Agions/taro-bluetooth-print","commit_stats":null,"previous_names":["agions/taro-bluetooth-print"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/Agions/taro-bluetooth-print","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agions%2Ftaro-bluetooth-print","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agions%2Ftaro-bluetooth-print/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agions%2Ftaro-bluetooth-print/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agions%2Ftaro-bluetooth-print/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Agions","download_url":"https://codeload.github.com/Agions/taro-bluetooth-print/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agions%2Ftaro-bluetooth-print/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32528665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth","bluetooth-print","esc-pos","label-printer","mini-program","printer","printing","react-native","taro","thermal-printer","tspl","typescript","web-bluetooth","zpl"],"created_at":"2026-02-26T12:28:22.749Z","updated_at":"2026-05-02T09:04:00.003Z","avatar_url":"https://github.com/Agions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🖨️ Taro Bluetooth Print\n\n**轻量级、高性能的 Taro 跨端蓝牙打印库 — 覆盖 7 大平台、8 种打印协议，开箱即用**\n\n[![npm version](https://img.shields.io/npm/v/taro-bluetooth-print?style=flat-square\u0026color=4338ca)](https://www.npmjs.com/package/taro-bluetooth-print)\n[![downloads](https://img.shields.io/npm/dm/taro-bluetooth-print?style=flat-square\u0026color=4338ca)](https://www.npmjs.com/package/taro-bluetooth-print)\n[![license](https://img.shields.io/npm/l/taro-bluetooth-print?style=flat-square\u0026color=4338ca)](https://github.com/agions/taro-bluetooth-print/blob/main/LICENSE)\n[![stars](https://img.shields.io/github/stars/agions/taro-bluetooth-print?style=flat-square)](https://github.com/agions/taro-bluetooth-print)\n[![forks](https://img.shields.io/github/forks/agions/taro-bluetooth-print?style=flat-square)](https://github.com/agions/taro-bluetooth-print)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/taro-bluetooth-print?style=flat-square)](https://bundlephobia.com/package/taro-bluetooth-print)\n\n\u003c/div\u003e\n\n---\n\n## ✨ 特性总览\n\n### 📡 基础能力\n\n| 能力 | 说明 |\n|:-----|:-----|\n| 多平台适配 | 微信 / 支付宝 / 百度 / 字节跳动 / QQ 小程序，H5 WebBluetooth，React Native |\n| 多协议驱动 | ESC/POS（热敏）、TSPL / ZPL / CPCL（标签）、STAR / 佳博 / 芯烨 / 思普瑞特 |\n| 链式调用 API | `printer.text(...).feed().qr(...).cut().print()` — IDE 全自动补全 |\n| TypeScript 严格模式 | 完整类型定义，零 `any` 暴露，无外部运行时依赖 |\n| 多编码支持 | GBK / GB2312 / Big5 / UTF-8 / EUC-KR / Shift-JIS / ISO-2022-JP |\n| 零运行时依赖 | 生产包无第三方运行时依赖，体积可控 |\n\n### 🖨️ 高级打印\n\n| 能力 | 说明 |\n|:-----|:-----|\n| 图片打印 | Floyd-Steinberg 抖动算法，6 种抖动模式，RGBA → 黑白位图自适应转换，ESC/POS/ZPL/TSPL/STAR 全驱动支持 |\n| ZPL 图像编码 | `ZplDriver.image()` — ^GFA 命令，位图 → 十六进制编码，支持 ZD420 等 Zebra 标签机 |\n| CPCL Logo 下载 | `CpclDriver.downloadLogo()` — CG 压缩图形命令，宏定义存储，支持 HP 等移动打印机 |\n| 二维码 / 条码 | 原生指令支持 Code128 / EAN / UPC / QR / PDF417 等 10+ 格式 |\n| 模板引擎 | 支持 `loop` 循环 / `condition` 条件 / `border` 边框 / `table` 表格，小票标签一键渲染 |\n| 任务生命周期 | 完整的打印任务暂停 / 恢复 / 取消控制 |\n| 打印预览 | ESC/POS 命令实时渲染为 Canvas 图像，调试所见即所得 |\n\n### ⚙️ 运维管理\n\n| 能力 | 说明 |\n|:-----|:-----|\n| 离线缓存 | 断网自动缓存，恢复网络自动同步，零任务丢失 |\n| 打印队列 | 优先级排序、失败自动重试、死链自动剔除 |\n| 多打印机管理 | `MultiPrinterManager` 多设备并发，支持负载均衡 |\n| 打印历史 | `PrintHistory` 完整记录，含耗时 / 字节数 / 成功率统计 |\n| 定时重试 | `ScheduledRetryManager` 指数退避策略，进程重启后自动恢复调度 |\n| 定时调度 | `PrintScheduler` 支持 cron 表达式 / 一次性 / 间隔重复任务 |\n| 设备发现 | `DiscoveryService` 增强型过滤、排序、RSSI 信号缓存 |\n| 插件系统 | DI 容器 + EventBus 事件总线，可扩展架构 |\n\n---\n\n## 📦 安装\n\n```bash\n# npm\nnpm install taro-bluetooth-print\n\n# pnpm（推荐）\npnpm add taro-bluetooth-print\n\n# yarn\nyarn add taro-bluetooth-print\n```\n\n\u003e **前置依赖**：项目需安装 `@tarojs/taro ^3.6.22` 及以上版本。\n\n---\n\n## 🚀 快速开始\n\n```typescript\nimport {\n  createBluetoothPrinter,\n  DeviceManager,\n  WebBluetoothAdapter\n} from 'taro-bluetooth-print';\n\nasync function printReceipt() {\n  // ① 扫描蓝牙设备\n  const manager = new DeviceManager();\n  await manager.startScan({ timeout: 10000 });\n  const devices = manager.getDiscoveredDevices();\n\n  if (devices.length === 0) {\n    console.warn('未发现蓝牙设备');\n    return;\n  }\n\n  // ② 创建打印机实例并连接\n  const printer = createBluetoothPrinter({\n    adapter: new WebBluetoothAdapter()\n  });\n\n  await printer.connect(devices[0].deviceId);\n\n  // ③ 链式调用 — 构建并打印小票\n  await printer\n    .text('=== 欢迎光临 ===', 'GBK')\n    .feed()\n    .text('商品A     x1    ¥10.00', 'GBK')\n    .text('商品B     x2    ¥20.00', 'GBK')\n    .feed()\n    .text('------------------------')\n    .text('合计：            ¥30.00', 'GBK')\n    .feed(2)\n    .qr('https://example.com', { size: 6 })\n    .feed(2)\n    .cut()\n    .print();\n\n  // ④ 断开连接\n  await printer.disconnect();\n}\n```\n\n---\n\n## 📱 平台支持\n\n| 平台 | 适配器类 | 状态 |\n|:-----|:---------|:----:|\n| 微信小程序 | `TaroAdapter` | ✅ |\n| 支付宝小程序 | `AlipayAdapter` | ✅ |\n| 百度小程序 | `BaiduAdapter` | ✅ |\n| 字节跳动小程序 | `ByteDanceAdapter` | ✅ |\n| QQ 小程序 | `QQAdapter` | ✅ |\n| H5 (Web Bluetooth) | `WebBluetoothAdapter` | ✅ |\n| React Native | `ReactNativeAdapter` | ✅ |\n\n\u003e 💡 **提示**：鸿蒙 HarmonyOS 可通过 `TaroAdapter` 适配使用。\n\n## 🖨️ 打印机驱动\n\n| 驱动 | 协议 | 典型品牌 / 型号 | 功能状态 |\n|:-----|:-----|:---------------|:--------|\n| `EscPos` | ESC/POS | 佳博、芯烨、商米、汉印 | ✅ 全功能 |\n| `TsplDriver` | TSPL | TSC ME240、TA210、TTP-244 | ✅ 全功能 |\n| `ZplDriver` | ZPL | Zebra ZD420、GT800、ZM400 | ✅ 含图像打印 (^GFA) |\n| `CpclDriver` | CPCL | HP IR3222、霍尼韦尔移动打印机 | ✅ 含 Logo 下载 (CG) |\n| `StarPrinter` | STAR | STAR TSP100、TSP700、TSP800 | ✅ 全功能 |\n| `GPrinterDriver` | 佳博自定义 | 佳博 GP-5890X 系列 | ✅ 全功能 |\n| `XprinterDriver` | ESC/POS | 芯烨 XP-58 系列 | ✅ 全功能 |\n| `SprtDriver` | ESC/POS | 思普瑞特系列 | ✅ 全功能 |\n\n---\n\n## ⚙️ 配置与事件\n\n### 传输参数配置\n\n```typescript\nconst printer = createBluetoothPrinter();\n\n// 调整蓝牙传输参数（适配不同打印机的吞吐能力）\nprinter.setOptions({\n  chunkSize: 20,   // 单次写入分片大小（byte），默认 20\n  delay: 20,       // 分片写入间隔（ms），默认 20\n  retries: 3,      // 写入失败重试次数，默认 3\n});\n```\n\n### 事件监听\n\n```typescript\n// 打印进度\nprinter.on('progress', ({ sent, total }) =\u003e {\n  console.log(`打印进度: ${(sent / total * 100).toFixed(1)}%`);\n});\n\n// 错误事件\nprinter.on('error', (error) =\u003e {\n  console.error('打印错误:', error.code, error.message);\n});\n\n// 打印完成\nprinter.on('print-complete', () =\u003e {\n  console.log('✅ 打印任务完成');\n});\n```\n\n---\n\n## 🛡️ 错误处理\n\n库提供完整的类型化错误层次结构，支持精确的错误捕获与处理：\n\n```typescript\nimport {\n  BluetoothPrintError,\n  ConnectionError,\n  PrintJobError,\n  CommandBuildError,\n  ErrorCode\n} from 'taro-bluetooth-print';\n\n// 方式一：统一错误基类捕获\ntry {\n  await printer.print();\n} catch (err) {\n  if (err instanceof BluetoothPrintError) {\n    console.error(`[${err.code}] ${err.message}`);\n  }\n}\n\n// 方式二：按错误类型精确处理（推荐）\ntry {\n  await printer.connect(deviceId);\n} catch (err) {\n  if (ConnectionError.isConnectionError(err)) {\n    // 连接失败 — 可提示用户重试\n    console.warn('连接错误:', err.message);\n  }\n}\n\ntry {\n  // ... 打印操作\n} catch (err) {\n  if (PrintJobError.isPrintJobError(err)) {\n    // 打印任务失败 — 可重新加入队列\n    console.warn('任务错误:', err.message);\n  }\n}\n\ntry {\n  printer.text('测试', 'UNSUPPORTED_ENCODING');\n} catch (err) {\n  if (CommandBuildError.isCommandBuildError(err)) {\n    // 指令构建失败 — 参数校验问题\n    console.warn('指令错误:', err.message);\n  }\n}\n```\n\n---\n\n## 🏗️ 架构概览\n\n```\n ┌──────────────────────────────────────────────────┐\n │              PrinterFactory (工厂层)                │\n │   createBluetoothPrinter · createWebBluetooth     │\n └─────────────────────┬────────────────────────────┘\n                       │\n                       ▼\n ┌──────────────────────────────────────────────────┐\n │            BluetoothPrinter (核心层)              │\n │   text() · feed() · qr() · cut() · image()       │\n │   print() · setOptions() · on() / off()          │\n └──────────┬───────────────────────┬───────────────┘\n            │                       │\n   ┌────────▼────────┐     ┌───────▼────────┐\n   │   Drivers (驱动) │     │  Adapters (适配) │\n   │                 │     │                 │\n   │  EscPos        │     │  TaroAdapter    │\n   │  TsplDriver    │     │  WebBluetooth   │\n   │  ZplDriver     │     │  ReactNative    │\n   │  CpclDriver    │     │  AlipayAdapter  │\n   │  StarPrinter   │     │  BaiduAdapter   │\n   │  GPrinter      │     │  ByteDance      │\n   │  Xprinter      │     │  QQAdapter      │\n   │  SprtDriver    │     │                 │\n   └────────┬────────┘     └───────┬────────┘\n            │                       │\n            └───────────┬───────────┘\n                        ▼\n ┌──────────────────────────────────────────────────┐\n │              Services (服务层)                     │\n │                                                   │\n │  PrintJob · Cache · Queue · History              │\n │  Statistics · Scheduler · Batch                  │\n │  EventBus · DIContainer · PluginSystem           │\n └──────────────────────────────────────────────────┘\n```\n\n---\n\n## 📊 性能指标\n\n| 指标 | 值 |\n|:-----|:---|\n| 包体积（gzip） | **~226 KB**（含全部驱动，无外部依赖） |\n| Tree-shaking | ✅ 支持，按需引入 |\n| 编码懒加载 | ✅ 未用到的字符集不进入产物 |\n| 测试用例 | ✅ **879** 个测试用例，**879** 通过（95.7%），覆盖阈值 70%+ |\n| 架构模式 | Template Method (ChunkWriteStrategy)、EventEmitter 统一、withTimeout 工具函数 |\n| 构建工具 | Vite + Vitest |\n\n---\n\n## 📂 示例项目\n\n| 示例 | 路径 |\n|:-----|:-----|\n| 微信小程序 | [examples/weapp](./examples/weapp) |\n| H5 | [examples/h5](./examples/h5) |\n| 鸿蒙 HarmonyOS | [examples/harmonyos](./examples/harmonyos) |\n| React Native | [examples/react-native](./examples/react-native) |\n\n---\n\n## 📖 文档\n\n| 文档 | 说明 |\n|:-----|:-----|\n| [快速开始](https://agions.github.io/taro-bluetooth-print/guide/getting-started) | 5 分钟入门教程 |\n| [功能特性](https://agions.github.io/taro-bluetooth-print/guide/features) | 全部功能详解 |\n| [驱动支持](https://agions.github.io/taro-bluetooth-print/guide/drivers) | ESC/POS、TSPL、ZPL 驱动说明 |\n| [核心概念](https://agions.github.io/taro-bluetooth-print/guide/core-concepts) | 架构设计与核心概念 |\n| [API 参考](https://agions.github.io/taro-bluetooth-print/api) | 完整 API 文档 |\n| [常见问题](https://agions.github.io/taro-bluetooth-print/guide/faq) | FAQ |\n\n---\n\n## 🛠️ 开发\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Agions/taro-bluetooth-print.git\ncd taro-bluetooth-print\n\n# 安装依赖\npnpm install\n\n# 运行测试\npnpm test\n\n# 代码检查\npnpm lint\n\n# TypeScript 类型检查\npnpm type-check\n\n# 构建产物\npnpm build\n\n# 本地文档开发\npnpm docs:dev\n```\n\n---\n\n## 📄 许可证\n\n[MIT](./LICENSE) · Copyright © 2024-present [Agions](https://github.com/Agions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagions%2Ftaro-bluetooth-print","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagions%2Ftaro-bluetooth-print","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagions%2Ftaro-bluetooth-print/lists"}