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.
- package/CHANGELOG.md +72 -90
- package/README.md +195 -248
- package/dist/index.cjs.js +1 -1
- package/dist/index.es.js +1 -1
- package/dist/index.umd.js +1 -1
- package/dist/types/adapters/AlipayAdapter.d.ts +0 -14
- package/dist/types/adapters/BaiduAdapter.d.ts +0 -14
- package/dist/types/adapters/BaseAdapter.d.ts +9 -3
- package/dist/types/adapters/ByteDanceAdapter.d.ts +0 -14
- package/dist/types/adapters/QQAdapter.d.ts +0 -18
- package/dist/types/adapters/TaroAdapter.d.ts +0 -14
- package/dist/types/core/BluetoothPrinter.d.ts +43 -287
- package/dist/types/drivers/{escPosDriver.d.ts → EscPosDriver.d.ts} +6 -0
- package/dist/types/drivers/GPrinterDriver.d.ts +1 -1
- package/dist/types/drivers/SprtDriver.d.ts +1 -1
- package/dist/types/drivers/XprinterDriver.d.ts +1 -1
- package/dist/types/drivers/index.d.ts +1 -1
- package/dist/types/encoding/index.d.ts +2 -2
- package/dist/types/errors/{baseError.d.ts → BaseError.d.ts} +6 -0
- package/dist/types/errors/CommandBuildError.d.ts +3 -17
- package/dist/types/errors/ConnectionError.d.ts +3 -20
- package/dist/types/errors/PrintJobError.d.ts +2 -18
- package/dist/types/errors/index.d.ts +1 -1
- package/dist/types/index.d.ts +3 -2
- package/dist/types/plugins/PluginManager.d.ts +2 -2
- package/dist/types/plugins/{types.d.ts → PluginTypes.d.ts} +1 -1
- package/dist/types/plugins/builtin/LoggingPlugin.d.ts +1 -1
- package/dist/types/plugins/builtin/RetryPlugin.d.ts +2 -2
- package/dist/types/plugins/index.d.ts +1 -1
- package/dist/types/services/CommandBuilder.d.ts +8 -151
- package/dist/types/services/ConnectionManager.d.ts +6 -1
- package/dist/types/services/PrintHistory.d.ts +14 -27
- package/dist/types/services/PrintJobManager.d.ts +24 -140
- package/dist/types/utils/BoundedOrderedMap.d.ts +47 -0
- package/package.json +4 -2
- package/src/adapters/AdapterFactory.ts +1 -1
- package/src/adapters/AlipayAdapter.ts +3 -21
- package/src/adapters/BaiduAdapter.ts +3 -21
- package/src/adapters/BaseAdapter.ts +27 -18
- package/src/adapters/ByteDanceAdapter.ts +3 -21
- package/src/adapters/ChunkWriteStrategy.ts +1 -1
- package/src/adapters/QQAdapter.ts +3 -25
- package/src/adapters/ReactNativeAdapter.ts +7 -5
- package/src/adapters/TaroAdapter.ts +5 -20
- package/src/adapters/WebBluetoothAdapter.ts +1 -1
- package/src/config/PrinterConfigManager.ts +1 -1
- package/src/core/BluetoothPrinter.ts +114 -421
- package/src/device/DeviceManager.ts +1 -1
- package/src/device/MultiPrinterManager.ts +1 -1
- package/src/drivers/CpclDriver.ts +1 -1
- package/src/drivers/{escPosDriver.ts → EscPosDriver.ts} +14 -15
- package/src/drivers/GPrinterDriver.ts +1 -1
- package/src/drivers/SprtDriver.ts +1 -1
- package/src/drivers/XprinterDriver.ts +1 -1
- package/src/drivers/ZplDriver.ts +1 -1
- package/src/drivers/index.ts +1 -1
- package/src/encoding/EncodingService.ts +2 -2
- package/src/encoding/{gbk-table.ts → GbkTable.ts} +2 -2
- package/src/encoding/index.ts +2 -2
- package/src/errors/{baseError.ts → BaseError.ts} +9 -0
- package/src/errors/CommandBuildError.ts +19 -30
- package/src/errors/ConnectionError.ts +9 -37
- package/src/errors/PrintJobError.ts +10 -32
- package/src/errors/index.ts +1 -1
- package/src/factory/PrinterFactory.ts +1 -1
- package/src/index.ts +3 -2
- package/src/plugins/PluginManager.ts +7 -5
- package/src/plugins/{types.ts → PluginTypes.ts} +1 -1
- package/src/plugins/builtin/LoggingPlugin.ts +1 -1
- package/src/plugins/builtin/RetryPlugin.ts +2 -2
- package/src/plugins/index.ts +1 -1
- package/src/preview/PreviewRenderer.ts +1 -1
- package/src/queue/PrintQueue.ts +1 -1
- package/src/services/BatchPrintManager.ts +1 -1
- package/src/services/CloudPrintManager.ts +1 -1
- package/src/services/CommandBuilder.ts +35 -193
- package/src/services/ConnectionManager.ts +28 -21
- package/src/services/PrintHistory.ts +43 -120
- package/src/services/PrintJobManager.ts +148 -331
- package/src/services/PrintScheduler.ts +1 -1
- package/src/template/engines/TemplateRenderer.ts +1 -1
- package/src/utils/BoundedOrderedMap.ts +120 -0
- package/src/utils/image.ts +1 -1
- package/dist/types/utils/errorHandler.d.ts +0 -78
- package/dist/types/utils/validation.d.ts +0 -8
- package/src/utils/errorHandler.ts +0 -196
- package/src/utils/validation.ts +0 -9
- /package/dist/types/drivers/{barcode-helpers.d.ts → BarcodeHelpers.d.ts} +0 -0
- /package/dist/types/encoding/{gbk-data.d.ts → GbkData.d.ts} +0 -0
- /package/dist/types/encoding/{gbk-lite.d.ts → GbkLite.d.ts} +0 -0
- /package/dist/types/encoding/{gbk-table.d.ts → GbkTable.d.ts} +0 -0
- /package/dist/types/encoding/{korean-japanese.d.ts → KoreanJapanese.d.ts} +0 -0
- /package/src/drivers/{barcode-helpers.ts → BarcodeHelpers.ts} +0 -0
- /package/src/encoding/{gbk-data.ts → GbkData.ts} +0 -0
- /package/src/encoding/{gbk-lite.ts → GbkLite.ts} +0 -0
- /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
|
-
|
|
3
|
+
<img src="docs/public/logo.svg" alt="taro-bluetooth-print" width="120" />
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
# taro-bluetooth-print
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
[](https://www.npmjs.com/package/taro-bluetooth-print)
|
|
12
|
+
[](https://www.npmjs.com/package/taro-bluetooth-print)
|
|
13
|
+
[](https://bundlephobia.com/package/taro-bluetooth-print)
|
|
14
|
+
[](https://github.com/agions/taro-bluetooth-print/blob/main/LICENSE)
|
|
15
|
+
[](https://github.com/agions/taro-bluetooth-print)
|
|
16
|
+
[](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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
|
34
|
-
|
|
35
|
-
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
const devices = manager.getDiscoveredDevices();
|
|
77
|
+
// ① 创建打印机(自动 dispatch 当前平台适配器)
|
|
78
|
+
const printer = createBluetoothPrinter({
|
|
79
|
+
adapter: new WebBluetoothAdapter(),
|
|
80
|
+
});
|
|
89
81
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
-
|
|
|
155
|
+
| 百度智能小程序 | `BaiduAdapter` | ✅ |
|
|
131
156
|
| 字节跳动小程序 | `ByteDanceAdapter` | ✅ |
|
|
132
157
|
| QQ 小程序 | `QQAdapter` | ✅ |
|
|
133
|
-
| H5
|
|
158
|
+
| H5(Web 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, //
|
|
163
|
-
delay: 20, //
|
|
164
|
-
retries: 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(
|
|
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
|
-
|
|
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
|
-
|
|
218
|
-
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
|
|
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
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
-
| 包体积(
|
|
289
|
-
|
|
|
290
|
-
|
|
|
291
|
-
|
|
|
292
|
-
|
|
|
293
|
-
|
|
|
294
|
-
|
|
|
295
|
-
|
|
|
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
|
-
|
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
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
|
-
| [
|
|
315
|
-
| [
|
|
316
|
-
| [
|
|
317
|
-
| [
|
|
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
|
-
|
|
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
|
-
|
|
300
|
+
</div>
|