taro-bluetooth-print 2.13.0 → 2.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +72 -90
  2. package/README.md +195 -248
  3. package/dist/index.cjs.js +1 -1
  4. package/dist/index.es.js +1 -1
  5. package/dist/index.umd.js +1 -1
  6. package/dist/types/adapters/AlipayAdapter.d.ts +0 -14
  7. package/dist/types/adapters/BaiduAdapter.d.ts +0 -14
  8. package/dist/types/adapters/BaseAdapter.d.ts +9 -3
  9. package/dist/types/adapters/ByteDanceAdapter.d.ts +0 -14
  10. package/dist/types/adapters/QQAdapter.d.ts +0 -18
  11. package/dist/types/adapters/TaroAdapter.d.ts +0 -14
  12. package/dist/types/core/BluetoothPrinter.d.ts +43 -287
  13. package/dist/types/drivers/{escPosDriver.d.ts → EscPosDriver.d.ts} +6 -0
  14. package/dist/types/drivers/GPrinterDriver.d.ts +1 -1
  15. package/dist/types/drivers/SprtDriver.d.ts +1 -1
  16. package/dist/types/drivers/XprinterDriver.d.ts +1 -1
  17. package/dist/types/drivers/index.d.ts +1 -1
  18. package/dist/types/encoding/index.d.ts +2 -2
  19. package/dist/types/errors/{baseError.d.ts → BaseError.d.ts} +6 -0
  20. package/dist/types/errors/CommandBuildError.d.ts +3 -17
  21. package/dist/types/errors/ConnectionError.d.ts +3 -20
  22. package/dist/types/errors/PrintJobError.d.ts +2 -18
  23. package/dist/types/errors/index.d.ts +1 -1
  24. package/dist/types/index.d.ts +3 -2
  25. package/dist/types/plugins/PluginManager.d.ts +2 -2
  26. package/dist/types/plugins/{types.d.ts → PluginTypes.d.ts} +1 -1
  27. package/dist/types/plugins/builtin/LoggingPlugin.d.ts +1 -1
  28. package/dist/types/plugins/builtin/RetryPlugin.d.ts +2 -2
  29. package/dist/types/plugins/index.d.ts +1 -1
  30. package/dist/types/services/CommandBuilder.d.ts +8 -151
  31. package/dist/types/services/ConnectionManager.d.ts +6 -1
  32. package/dist/types/services/PrintHistory.d.ts +14 -27
  33. package/dist/types/services/PrintJobManager.d.ts +24 -140
  34. package/dist/types/utils/BoundedOrderedMap.d.ts +47 -0
  35. package/package.json +4 -2
  36. package/src/adapters/AdapterFactory.ts +1 -1
  37. package/src/adapters/AlipayAdapter.ts +3 -21
  38. package/src/adapters/BaiduAdapter.ts +3 -21
  39. package/src/adapters/BaseAdapter.ts +27 -18
  40. package/src/adapters/ByteDanceAdapter.ts +3 -21
  41. package/src/adapters/ChunkWriteStrategy.ts +1 -1
  42. package/src/adapters/QQAdapter.ts +3 -25
  43. package/src/adapters/ReactNativeAdapter.ts +7 -5
  44. package/src/adapters/TaroAdapter.ts +5 -20
  45. package/src/adapters/WebBluetoothAdapter.ts +1 -1
  46. package/src/config/PrinterConfigManager.ts +1 -1
  47. package/src/core/BluetoothPrinter.ts +114 -421
  48. package/src/device/DeviceManager.ts +1 -1
  49. package/src/device/MultiPrinterManager.ts +1 -1
  50. package/src/drivers/CpclDriver.ts +1 -1
  51. package/src/drivers/{escPosDriver.ts → EscPosDriver.ts} +14 -15
  52. package/src/drivers/GPrinterDriver.ts +1 -1
  53. package/src/drivers/SprtDriver.ts +1 -1
  54. package/src/drivers/XprinterDriver.ts +1 -1
  55. package/src/drivers/ZplDriver.ts +1 -1
  56. package/src/drivers/index.ts +1 -1
  57. package/src/encoding/EncodingService.ts +2 -2
  58. package/src/encoding/{gbk-table.ts → GbkTable.ts} +2 -2
  59. package/src/encoding/index.ts +2 -2
  60. package/src/errors/{baseError.ts → BaseError.ts} +9 -0
  61. package/src/errors/CommandBuildError.ts +19 -30
  62. package/src/errors/ConnectionError.ts +9 -37
  63. package/src/errors/PrintJobError.ts +10 -32
  64. package/src/errors/index.ts +1 -1
  65. package/src/factory/PrinterFactory.ts +1 -1
  66. package/src/index.ts +3 -2
  67. package/src/plugins/PluginManager.ts +7 -5
  68. package/src/plugins/{types.ts → PluginTypes.ts} +1 -1
  69. package/src/plugins/builtin/LoggingPlugin.ts +1 -1
  70. package/src/plugins/builtin/RetryPlugin.ts +2 -2
  71. package/src/plugins/index.ts +1 -1
  72. package/src/preview/PreviewRenderer.ts +1 -1
  73. package/src/queue/PrintQueue.ts +1 -1
  74. package/src/services/BatchPrintManager.ts +1 -1
  75. package/src/services/CloudPrintManager.ts +1 -1
  76. package/src/services/CommandBuilder.ts +35 -193
  77. package/src/services/ConnectionManager.ts +28 -21
  78. package/src/services/PrintHistory.ts +43 -120
  79. package/src/services/PrintJobManager.ts +148 -331
  80. package/src/services/PrintScheduler.ts +1 -1
  81. package/src/template/engines/TemplateRenderer.ts +1 -1
  82. package/src/utils/BoundedOrderedMap.ts +120 -0
  83. package/src/utils/image.ts +1 -1
  84. package/dist/types/utils/errorHandler.d.ts +0 -78
  85. package/dist/types/utils/validation.d.ts +0 -8
  86. package/src/utils/errorHandler.ts +0 -196
  87. package/src/utils/validation.ts +0 -9
  88. /package/dist/types/drivers/{barcode-helpers.d.ts → BarcodeHelpers.d.ts} +0 -0
  89. /package/dist/types/encoding/{gbk-data.d.ts → GbkData.d.ts} +0 -0
  90. /package/dist/types/encoding/{gbk-lite.d.ts → GbkLite.d.ts} +0 -0
  91. /package/dist/types/encoding/{gbk-table.d.ts → GbkTable.d.ts} +0 -0
  92. /package/dist/types/encoding/{korean-japanese.d.ts → KoreanJapanese.d.ts} +0 -0
  93. /package/src/drivers/{barcode-helpers.ts → BarcodeHelpers.ts} +0 -0
  94. /package/src/encoding/{gbk-data.ts → GbkData.ts} +0 -0
  95. /package/src/encoding/{gbk-lite.ts → GbkLite.ts} +0 -0
  96. /package/src/encoding/{korean-japanese.ts → KoreanJapanese.ts} +0 -0
package/README.md CHANGED
@@ -1,61 +1,60 @@
1
1
  <div align="center">
2
2
 
3
- # 🖨️ Taro Bluetooth Print
3
+ <img src="docs/public/logo.svg" alt="taro-bluetooth-print" width="120" />
4
4
 
5
- **轻量级、高性能的 Taro 跨端蓝牙打印库 — 覆盖 7 大平台、8 种打印协议,开箱即用**
5
+ # taro-bluetooth-print
6
6
 
7
- [![npm version](https://img.shields.io/npm/v/taro-bluetooth-print?style=flat-square&color=4338ca)](https://www.npmjs.com/package/taro-bluetooth-print)
8
- [![downloads](https://img.shields.io/npm/dm/taro-bluetooth-print?style=flat-square&color=4338ca)](https://www.npmjs.com/package/taro-bluetooth-print)
9
- [![license](https://img.shields.io/npm/l/taro-bluetooth-print?style=flat-square&color=4338ca)](https://github.com/agions/taro-bluetooth-print/blob/main/LICENSE)
10
- [![stars](https://img.shields.io/github/stars/agions/taro-bluetooth-print?style=flat-square)](https://github.com/agions/taro-bluetooth-print)
11
- [![forks](https://img.shields.io/github/forks/agions/taro-bluetooth-print?style=flat-square)](https://github.com/agions/taro-bluetooth-print)
12
- [![bundle size](https://img.shields.io/bundlephobia/minzip/taro-bluetooth-print?style=flat-square)](https://bundlephobia.com/package/taro-bluetooth-print)
7
+ **轻量级、高性能的 Taro 跨端蓝牙打印库**
8
+
9
+ *一套代码,七大平台全覆盖;八种打印协议,开箱即用。*
10
+
11
+ [![npm version](https://img.shields.io/npm/v/taro-bluetooth-print?style=flat-square&color=4338ca&labelColor=1e1b4b)](https://www.npmjs.com/package/taro-bluetooth-print)
12
+ [![downloads](https://img.shields.io/npm/dm/taro-bluetooth-print?style=flat-square&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/taro-bluetooth-print)
13
+ [![bundle size](https://img.shields.io/bundlephobia/minzip/taro-bluetooth-print?style=flat-square&color=0891b2&labelColor=1e1b4b)](https://bundlephobia.com/package/taro-bluetooth-print)
14
+ [![license](https://img.shields.io/npm/l/taro-bluetooth-print?style=flat-square&color=4338ca&labelColor=1e1b4b)](https://github.com/agions/taro-bluetooth-print/blob/main/LICENSE)
15
+ [![stars](https://img.shields.io/github/stars/agions/taro-bluetooth-print?style=flat-square&label=⭐+Stars)](https://github.com/agions/taro-bluetooth-print)
16
+ [![CI](https://img.shields.io/github/actions/workflow/status/agions/taro-bluetooth-print/ci.yml?style=flat-square&label=CI)](https://github.com/agions/taro-bluetooth-print/actions)
17
+
18
+ [🚀 快速开始](#-快速开始) · [📖 完整文档](https://agions.github.io/taro-bluetooth-print/) · [🧩 在线示例](https://github.com/Agions/taro-bluetooth-print/tree/main/examples) · [💬 讨论](https://github.com/Agions/taro-bluetooth-print/discussions)
13
19
 
14
20
  </div>
15
21
 
16
22
  ---
17
23
 
18
- ## ✨ 特性总览
19
-
20
- ### 📡 基础能力
21
-
22
- | 能力 | 说明 |
23
- |:-----|:-----|
24
- | 多平台适配 | 微信 / 支付宝 / 百度 / 字节跳动 / QQ 小程序,H5 WebBluetooth,React Native |
25
- | 多协议驱动 | ESC/POS(热敏)、TSPL / ZPL / CPCL(标签)、STAR / 佳博 / 芯烨 / 思普瑞特 |
26
- | 链式调用 API | `printer.text(...).feed().qr(...).cut().print()` — IDE 全自动补全 |
27
- | TypeScript 严格模式 | 完整类型定义,零 `any` 暴露,无外部运行时依赖 |
28
- | 多编码支持 | GBK / GB2312 / Big5 / UTF-8 / EUC-KR / Shift-JIS / ISO-2022-JP |
29
- | 零运行时依赖 | 生产包无第三方运行时依赖,体积可控 |
30
-
31
- ### 🖨️ 高级打印
32
-
33
- | 能力 | 说明 |
34
- |:-----|:-----|
35
- | 图片打印 | Floyd-Steinberg 抖动算法,6 种抖动模式,RGBA 黑白位图自适应转换,ESC/POS/ZPL/TSPL/STAR 全驱动支持 |
36
- | ZPL 图像编码 | `ZplDriver.image()` — ^GFA 命令,位图 → 十六进制编码,支持 ZD420 等 Zebra 标签机 |
37
- | CPCL Logo 下载 | `CpclDriver.downloadLogo()` — CG 压缩图形命令,宏定义存储,支持 HP 等移动打印机 |
38
- | 二维码 / 条码 | 原生指令支持 Code128 / EAN / UPC / QR / PDF417 等 10+ 格式 |
39
- | 模板引擎 | 支持 `loop` 循环 / `condition` 条件 / `border` 边框 / `table` 表格,小票标签一键渲染 |
40
- | 任务生命周期 | 完整的打印任务暂停 / 恢复 / 取消控制 |
41
- | 打印预览 | ESC/POS 命令实时渲染为 Canvas 图像,调试所见即所得 |
42
-
43
- ### ⚙️ 运维管理
44
-
45
- | 能力 | 说明 |
46
- |:-----|:-----|
47
- | 离线缓存 | 断网自动缓存,恢复网络自动同步,零任务丢失 |
48
- | 打印队列 | 优先级排序、失败自动重试、死链自动剔除 |
49
- | 多打印机管理 | `MultiPrinterManager` 多设备并发,支持负载均衡 |
50
- | 打印历史 | `PrintHistory` 完整记录,含耗时 / 字节数 / 成功率统计 |
51
- | 定时重试 | `ScheduledRetryManager` 指数退避策略,进程重启后自动恢复调度 |
52
- | 定时调度 | `PrintScheduler` 支持 cron 表达式 / 一次性 / 间隔重复任务 |
53
- | 设备发现 | `DiscoveryService` 增强型过滤、排序、RSSI 信号缓存 |
54
- | 插件系统 | Hook-based 插件管理器,支持 beforePrint/afterPrint 等钩子 |
24
+ ## ✨ 为什么选择 taro-bluetooth-print
25
+
26
+ > 一个库,一套 API,覆盖**所有主流蓝牙打印机**与**所有 Taro 目标平台**。
27
+ > 零运行时依赖 · TypeScript 严格模式 · 完整类型定义 · 全栈分层架构。
28
+
29
+ ### 🛰️ **跨七平台、一处编写到处打印**
30
+
31
+ 不再为每个小程序平台写一份蓝牙适配代码——`TaroAdapter` / `AlipayAdapter` / `BaiduAdapter` / `ByteDanceAdapter` / `QQAdapter` / `WebBluetoothAdapter` / `ReactNativeAdapter` 共享统一 API,统统由 `AdapterFactory.create()` 自动 dispatch。
32
+
33
+ ### 🖨️ **八大驱动协议、商米到 Zebra 全场景**
34
+
35
+ | 协议 | 驱动类 | 适用机型 |
36
+ |:---:|:---|:---|
37
+ | **ESC/POS** | `EscPos` | 佳博、芯烨、商米、汉印、思普瑞特 |
38
+ | **TSPL** | `TsplDriver` | TSC ME240 / TA210 / TTP-244 等标签机 |
39
+ | **ZPL** | `ZplDriver` | Zebra ZD420 / GT800 / ZM400(含 ^GFA 图像) |
40
+ | **CPCL** | `CpclDriver` | HP IR3222、霍尼韦尔移动机(含 CG Logo 下载) |
41
+ | **STAR** | `StarPrinter` | STAR TSP100 / TSP700 / TSP800 |
42
+
43
+ ### 🧠 **完备的业务能力栈**
44
+
45
+ `PrintQueue` 优先级调度 `PrintJobManager` 状态机 → `OfflineCache` LRU + Base64 持久化 → `ScheduledRetryManager` 指数退避 `PrintScheduler` Cron 调度 `PrintHistory` 全链路统计 → `PluginManager` Hook 系统——把企业级打印场景抽象成可组合的 primitive。
46
+
47
+ ### 💎 **TypeScript 严格模式 · 零运行时依赖**
48
+
49
+ - 整个库 **0 个生产依赖**(仅 peerDep `@tarojs/taro ^3.6.22`)
50
+ - ✅ 严格类型契约 (`IPrinterDriver` / `IPrinterAdapter`),IDE 自动补全
51
+ - **1,102 个测试**全绿 · **jscpd 0 重复** · **零 dead code**
55
52
 
56
53
  ---
57
54
 
58
- ## 📦 安装
55
+ ## 🚀 快速开始
56
+
57
+ ### 📦 安装
59
58
 
60
59
  ```bash
61
60
  # npm
@@ -70,284 +69,232 @@ yarn add taro-bluetooth-print
70
69
 
71
70
  > **前置依赖**:项目需安装 `@tarojs/taro ^3.6.22` 及以上版本。
72
71
 
73
- ---
74
-
75
- ## 🚀 快速开始
72
+ ### ⚡ 30 秒打印一张小票
76
73
 
77
74
  ```typescript
78
- import {
79
- createBluetoothPrinter,
80
- DeviceManager,
81
- WebBluetoothAdapter
82
- } from 'taro-bluetooth-print';
75
+ import { createBluetoothPrinter, WebBluetoothAdapter } from 'taro-bluetooth-print';
83
76
 
84
- async function printReceipt() {
85
- // 扫描蓝牙设备
86
- const manager = new DeviceManager();
87
- await manager.startScan({ timeout: 10000 });
88
- const devices = manager.getDiscoveredDevices();
77
+ // 创建打印机(自动 dispatch 当前平台适配器)
78
+ const printer = createBluetoothPrinter({
79
+ adapter: new WebBluetoothAdapter(),
80
+ });
89
81
 
90
- if (devices.length === 0) {
91
- console.warn('未发现蓝牙设备');
92
- return;
93
- }
82
+ // 连接 BLE 设备
83
+ await printer.connect('device-id-xxx');
84
+
85
+ // ③ 链式 API 构建小票
86
+ await printer
87
+ .text('=== 欢迎光临 ===', 'GBK')
88
+ .feed()
89
+ .text('商品A x1 ¥10.00', 'GBK')
90
+ .text('商品B x2 ¥20.00', 'GBK')
91
+ .feed()
92
+ .text('------------------------')
93
+ .text('合计: ¥30.00', 'GBK')
94
+ .feed(2)
95
+ .qr('https://example.com', { size: 6 })
96
+ .feed(2)
97
+ .cut()
98
+ .print();
99
+
100
+ // ④ 断开
101
+ await printer.disconnect();
102
+ ```
94
103
 
95
- // ② 创建打印机实例并连接
96
- const printer = createBluetoothPrinter({
97
- adapter: new WebBluetoothAdapter()
98
- });
99
-
100
- await printer.connect(devices[0].deviceId);
101
-
102
- // ③ 链式调用 — 构建并打印小票
103
- await printer
104
- .text('=== 欢迎光临 ===', 'GBK')
105
- .feed()
106
- .text('商品A x1 ¥10.00', 'GBK')
107
- .text('商品B x2 ¥20.00', 'GBK')
108
- .feed()
109
- .text('------------------------')
110
- .text('合计: ¥30.00', 'GBK')
111
- .feed(2)
112
- .qr('https://example.com', { size: 6 })
113
- .feed(2)
114
- .cut()
115
- .print();
116
-
117
- // ④ 断开连接
118
- await printer.disconnect();
119
- }
104
+ ---
105
+
106
+ ## 🏗️ 架构设计
107
+
108
+ 一个清晰的 6 层架构,每层只对相邻层有依赖,**严格遵循依赖倒置**:
109
+
110
+ ```mermaid
111
+ flowchart TB
112
+ App(["👤 应用代码<br/>(小票 / 标签)"])
113
+ subgraph Factory["🏭 Factory Layer"]
114
+ F1["createBluetoothPrinter()"]
115
+ end
116
+ subgraph Core["🎛️ Core Layer"]
117
+ BP["BluetoothPrinter<br/>(façade)"]
118
+ end
119
+ subgraph Services["⚙️ Service Layer"]
120
+ CM["ConnectionManager"]
121
+ JM["PrintJobManager"]
122
+ CB["CommandBuilder"]
123
+ end
124
+ subgraph Drivers["🖨️ Driver Layer"]
125
+ E1["EscPos"]
126
+ E2["TsplDriver"]
127
+ E3["ZplDriver"]
128
+ E4["CpclDriver"]
129
+ end
130
+ subgraph Adapters["📡 Adapter Layer"]
131
+ A1["TaroAdapter"]
132
+ A2["WebBluetoothAdapter"]
133
+ A3["ReactNativeAdapter"]
134
+ end
135
+ subgraph Errors["🛡️ Error Layer"]
136
+ ER["BluetoothPrintError"]
137
+ end
138
+ App --> F1 --> BP
139
+ BP --> Services
140
+ Services --> Drivers
141
+ Services --> Adapters
142
+ BP -.throws.-> ER
120
143
  ```
121
144
 
145
+ > 💡 每一层都可独立测试、独立替换。`PluginManager` 通过 hook 横切所有层。
146
+
122
147
  ---
123
148
 
124
149
  ## 📱 平台支持
125
150
 
126
- | 平台 | 适配器类 | 状态 |
127
- |:-----|:---------|:----:|
151
+ | 平台 | 适配器 | 状态 |
152
+ |:---|:---|:---:|
128
153
  | 微信小程序 | `TaroAdapter` | ✅ |
129
154
  | 支付宝小程序 | `AlipayAdapter` | ✅ |
130
- | 百度小程序 | `BaiduAdapter` | ✅ |
155
+ | 百度智能小程序 | `BaiduAdapter` | ✅ |
131
156
  | 字节跳动小程序 | `ByteDanceAdapter` | ✅ |
132
157
  | QQ 小程序 | `QQAdapter` | ✅ |
133
- | H5 (Web Bluetooth) | `WebBluetoothAdapter` | ✅ |
158
+ | H5Web Bluetooth | `WebBluetoothAdapter` | ✅ |
134
159
  | React Native | `ReactNativeAdapter` | ✅ |
135
-
136
- > 💡 **提示**:鸿蒙 HarmonyOS 可通过 `TaroAdapter` 适配使用。
137
-
138
- ## 🖨️ 打印机驱动
139
-
140
- | 驱动 | 协议 | 典型品牌 / 型号 | 功能状态 |
141
- |:-----|:-----|:---------------|:--------|
142
- | `EscPos` | ESC/POS | 佳博、芯烨、商米、汉印 | ✅ 全功能 |
143
- | `TsplDriver` | TSPL | TSC ME240、TA210、TTP-244 | ✅ 全功能 |
144
- | `ZplDriver` | ZPL | Zebra ZD420、GT800、ZM400 | ✅ 含图像打印 (^GFA) |
145
- | `CpclDriver` | CPCL | HP IR3222、霍尼韦尔移动打印机 | ✅ 含 Logo 下载 (CG) |
146
- | `StarPrinter` | STAR | STAR TSP100、TSP700、TSP800 | ✅ 全功能 |
147
- | `GPrinterDriver` | 佳博自定义 | 佳博 GP-5890X 系列 | ✅ 全功能 |
148
- | `XprinterDriver` | ESC/POS | 芯烨 XP-58 系列 | ✅ 全功能 |
149
- | `SprtDriver` | ESC/POS | 思普瑞特系列 | ✅ 全功能 |
160
+ | 鸿蒙 HarmonyOS | `TaroAdapter` | ✅ |
150
161
 
151
162
  ---
152
163
 
153
- ## ⚙️ 配置与事件
164
+ ## ⚙️ 传输参数 & 事件
154
165
 
155
- ### 传输参数配置
166
+ ### 传输调优
156
167
 
157
168
  ```typescript
158
- const printer = createBluetoothPrinter();
159
-
160
- // 调整蓝牙传输参数(适配不同打印机的吞吐能力)
161
169
  printer.setOptions({
162
- chunkSize: 20, // 单次写入分片大小(byte),默认 20
163
- delay: 20, // 分片写入间隔(ms),默认 20
164
- retries: 3, // 写入失败重试次数,默认 3
170
+ chunkSize: 20, // 单次 BLE 写入分片(默认 20
171
+ delay: 20, // 分片间隔 ms(默认 20
172
+ retries: 3, // 失败重试(默认 3
165
173
  });
166
174
  ```
167
175
 
168
- ### 事件监听
176
+ ### 事件订阅
169
177
 
170
178
  ```typescript
171
- // 打印进度
172
179
  printer.on('progress', ({ sent, total }) => {
173
- console.log(`打印进度: ${(sent / total * 100).toFixed(1)}%`);
174
- });
175
-
176
- // 错误事件
177
- printer.on('error', (error) => {
178
- console.error('打印错误:', error.code, error.message);
179
- });
180
-
181
- // 打印完成
182
- printer.on('print-complete', () => {
183
- console.log('✅ 打印任务完成');
180
+ console.log(`打印进度 ${((sent / total) * 100).toFixed(1)}%`);
184
181
  });
182
+ printer.on('error', err => console.error('打印错误:', err.code, err.message));
183
+ printer.on('print-complete', () => console.log('✅ 打印完成'));
185
184
  ```
186
185
 
187
186
  ---
188
187
 
189
- ## 🛡️ 错误处理
190
-
191
- 库提供完整的类型化错误层次结构,支持精确的错误捕获与处理:
188
+ ## 🛡️ 类型化错误处理
192
189
 
193
190
  ```typescript
194
191
  import {
195
- BluetoothPrintError,
196
- ConnectionError,
197
- PrintJobError,
198
- CommandBuildError,
199
- ErrorCode
192
+ BluetoothPrintError, ConnectionError, PrintJobError,
193
+ CommandBuildError, ErrorCode,
200
194
  } from 'taro-bluetooth-print';
201
195
 
202
- // 方式一:统一错误基类捕获
203
- try {
204
- await printer.print();
205
- } catch (err) {
206
- if (err instanceof BluetoothPrintError) {
207
- console.error(`[${err.code}] ${err.message}`);
208
- }
209
- }
210
-
211
- // 方式二:按错误类型精确处理(推荐)
212
196
  try {
213
197
  await printer.connect(deviceId);
214
198
  } catch (err) {
215
199
  if (ConnectionError.isConnectionError(err)) {
216
- // 连接失败可提示用户重试
217
- console.warn('连接错误:', err.message);
218
- }
219
- }
220
-
221
- try {
222
- // ... 打印操作
223
- } catch (err) {
224
- if (PrintJobError.isPrintJobError(err)) {
225
- // 打印任务失败 — 可重新加入队列
226
- console.warn('任务错误:', err.message);
227
- }
228
- }
229
-
230
- try {
231
- printer.text('测试', 'UNSUPPORTED_ENCODING');
232
- } catch (err) {
233
- if (CommandBuildError.isCommandBuildError(err)) {
234
- // 指令构建失败 — 参数校验问题
235
- console.warn('指令错误:', err.message);
200
+ // 连接层提示用户重试 / 切换设备
201
+ } else if (PrintJobError.isPrintJobError(err)) {
202
+ // 任务层 — 重新入队
203
+ } else if (CommandBuildError.isCommandBuildError(err)) {
204
+ // 指令层 — 检查参数
205
+ } else if (err instanceof BluetoothPrintError) {
206
+ // 兜底 — 任意已封装错误
236
207
  }
237
208
  }
238
209
  ```
239
210
 
240
211
  ---
241
212
 
242
- ## 🏗️ 架构概览
213
+ ## 🔌 插件系统
243
214
 
244
- ```
245
- ┌──────────────────────────────────────────────────┐
246
- │ PrinterFactory (工厂层) │
247
- │ createBluetoothPrinter · createWebBluetooth │
248
- └─────────────────────┬────────────────────────────┘
249
-
250
-
251
- ┌──────────────────────────────────────────────────┐
252
- │ BluetoothPrinter (核心层)
253
- │ text() · feed() · qr() · cut() · image() │
254
- │ print() · setOptions() · on() / off() │
255
- └──────────┬───────────────────────┬───────────────┘
256
- │ │
257
- ┌────────▼────────┐ ┌───────▼────────┐
258
- │ Drivers (驱动) │ │ Adapters (适配) │
259
- │ │ │ │
260
- │ EscPos │ │ TaroAdapter │
261
- │ TsplDriver │ │ WebBluetooth │
262
- │ ZplDriver │ │ ReactNative │
263
- │ CpclDriver │ │ AlipayAdapter │
264
- │ StarPrinter │ │ BaiduAdapter │
265
- │ GPrinter │ │ ByteDance │
266
- │ Xprinter │ │ QQAdapter │
267
- │ SprtDriver │ │ │
268
- └────────┬────────┘ └───────┬────────┘
269
- │ │
270
- └───────────┬───────────┘
271
-
272
- ┌──────────────────────────────────────────────────┐
273
- │ Services (服务层) │
274
- │ │
275
- │ ConnectionManager · PrintJobManager │
276
- │ CommandBuilder · PrintScheduler │
277
- │ PrintQueue · OfflineCache · PrintHistory │
278
- │ PluginManager (Hook-based) │
279
- └──────────────────────────────────────────────────┘
215
+ 无需侵入核心代码即可横切打印生命周期:
216
+
217
+ ```typescript
218
+ import { PrinterFactory, createLoggingPlugin, createRetryPlugin } from 'taro-bluetooth-print';
219
+
220
+ const printer = createBluetoothPrinter({ adapter: new WebBluetoothAdapter() });
221
+
222
+ printer.use(createLoggingPlugin({ level: 3 }));
223
+ printer.use(createRetryPlugin({ maxRetries: 3, backoffMultiplier: 2 }));
224
+
225
+ // Also built-in:
226
+ // · Logger plugin · Retry plugin
227
+ // · Or roll your own — see PluginManager docs
280
228
  ```
281
229
 
230
+ 钩子集:`beforeConnect` · `afterConnect` · `beforeDisconnect` · `afterDisconnect` · `beforePrint` · `afterPrint` · `onError` · `onStateChange` · `onProgress`
231
+
282
232
  ---
283
233
 
284
- ## 📊 性能指标
234
+ ## 📊 项目指标
285
235
 
286
- | 指标 | |
287
- |:-----|:---|
288
- | 包体积(gzip) | **~231 KB**(含全部驱动,无外部依赖) |
289
- | Tree-shaking | 支持,按需引入 |
290
- | 编码懒加载 | 未用到的字符集不进入产物 |
291
- | 测试用例 | **1,102** 个测试用例,全部通过 |
292
- | 代码重复率 | **0%**(jscpd 检测) |
293
- | 类型安全 | `any` 暴露,类型断言最小化 |
294
- | 架构模式 | Template Method (ChunkWriteStrategy)、EventEmitter 类型安全、Mixin 模式 |
295
- | 构建工具 | Vite + Vitest + TypeScript 严格模式 |
236
+ | 维度 | 数值 |
237
+ |:---|:---|
238
+ | 包体积(minzip) | **~231 KB** —— 零运行时依赖 |
239
+ | 测试用例 | **1,102** 个,全绿 |
240
+ | 代码重复 | **jscpd 0 clones** |
241
+ | 死代码 | **0 行** |
242
+ | TypeScript any 暴露 | **0 处** |
243
+ | 架构模式 | Template Method · Mixin · Facade · Strategy · EventEmitter |
244
+ | 模块数 | 14 个清晰分层 |
245
+ | API 公开方法 | 100+ 全部类型化 |
296
246
 
297
247
  ---
298
248
 
299
- ## 📂 示例项目
249
+ ## 📖 完整文档
300
250
 
301
- | 示例 | 路径 |
302
- |:-----|:-----|
303
- | 微信小程序 | [examples/weapp](./examples/weapp) |
304
- | H5 | [examples/h5](./examples/h5) |
305
- | 鸿蒙 HarmonyOS | [examples/harmonyos](./examples/harmonyos) |
306
- | React Native | [examples/react-native](./examples/react-native) |
251
+ | 入口 | 链接 |
252
+ |:---|:---|
253
+ | 快速开始 | [agions.github.io/taro-bluetooth-print/guide/getting-started](https://agions.github.io/taro-bluetooth-print/guide/getting-started) |
254
+ | 功能详解 | [/guide/features](https://agions.github.io/taro-bluetooth-print/guide/features) |
255
+ | 驱动支持 | [/guide/drivers](https://agions.github.io/taro-bluetooth-print/guide/drivers) |
256
+ | 架构设计 | [/guide/architecture](https://agions.github.io/taro-bluetooth-print/guide/architecture) |
257
+ | API 参考 | [/api/](https://agions.github.io/taro-bluetooth-print/api/) |
258
+ | FAQ | [/guide/faq](https://agions.github.io/taro-bluetooth-print/guide/faq) |
307
259
 
308
260
  ---
309
261
 
310
- ## 📖 文档
262
+ ## 🧪 示例项目
311
263
 
312
- | 文档 | 说明 |
313
- |:-----|:-----|
314
- | [快速开始](https://agions.github.io/taro-bluetooth-print/guide/getting-started) | 5 分钟入门教程 |
315
- | [功能特性](https://agions.github.io/taro-bluetooth-print/guide/features) | 全部功能详解 |
316
- | [驱动支持](https://agions.github.io/taro-bluetooth-print/guide/drivers) | ESC/POS、TSPL、ZPL 驱动说明 |
317
- | [核心概念](https://agions.github.io/taro-bluetooth-print/guide/core-concepts) | 架构设计与核心概念 |
318
- | [API 参考](https://agions.github.io/taro-bluetooth-print/api) | 完整 API 文档 |
319
- | [常见问题](https://agions.github.io/taro-bluetooth-print/guide/faq) | FAQ |
264
+ | 平台 | 路径 |
265
+ |:---|:---|
266
+ | 微信小程序 | [`examples/weapp`](./examples/weapp) |
267
+ | H5 | [`examples/h5`](./examples/h5) |
268
+ | React Native | [`examples/react-native`](./examples/react-native) |
269
+ | 鸿蒙 HarmonyOS | [`examples/harmonyos`](./examples/harmonyos) |
320
270
 
321
271
  ---
322
272
 
323
- ## 🛠️ 开发
273
+ ## 🛠️ 开发 & 贡献
324
274
 
325
275
  ```bash
326
- # 克隆仓库
327
276
  git clone https://github.com/Agions/taro-bluetooth-print.git
328
277
  cd taro-bluetooth-print
329
-
330
- # 安装依赖
331
278
  pnpm install
279
+ pnpm test # 1102 测试
280
+ pnpm lint # ESLint
281
+ pnpm type-check # tsc --noEmit
282
+ pnpm build # 产物输出到 dist/
283
+ pnpm docs:dev # 本地 VitePress 文档
284
+ ```
332
285
 
333
- # 运行测试
334
- pnpm test
286
+ 欢迎 PR 与 Issue!请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) · 提交前确保 `pnpm test && pnpm lint && pnpm type-check` 全绿 ✨
335
287
 
336
- # 代码检查
337
- pnpm lint
288
+ ---
338
289
 
339
- # TypeScript 类型检查
340
- pnpm type-check
290
+ ## 📄 许可证
341
291
 
342
- # 构建产物
343
- pnpm build
292
+ [MIT](./LICENSE) · Copyright © 2024-present [Agions](https://github.com/Agions)
344
293
 
345
- # 本地文档开发
346
- pnpm docs:dev
347
- ```
294
+ <div align="center">
348
295
 
349
- ---
296
+ **⭐ 觉得好用?给个 Star 支持一下开发喵~ ⭐**
350
297
 
351
- ## 📄 许可证
298
+ [Star on GitHub →](https://github.com/Agions/taro-bluetooth-print)
352
299
 
353
- [MIT](./LICENSE) · Copyright © 2024-present [Agions](https://github.com/Agions)
300
+ </div>