taro-bluetooth-print 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,81 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-01-04
+
+### Added
+
+- **设备管理器 (DeviceManager)** - 蓝牙设备扫描和管理功能
+  - 支持设备过滤（名称、服务UUID）
+  - 设备发现事件监听
+  - 已配对设备管理
+
+- **打印队列 (PrintQueue)** - 打印任务队列管理
+  - 优先级排序（LOW/NORMAL/HIGH/URGENT）
+  - FIFO 处理机制
+  - 失败自动重试
+  - 队列暂停/恢复/清空
+
+- **离线缓存 (OfflineCache)** - 断网时自动缓存打印任务
+  - 本地存储持久化
+  - 任务过期清理
+  - 重连后自动同步
+
+- **模板引擎 (TemplateEngine)** - 收据和标签模板渲染
+  - 内置收据模板（店铺信息、商品列表、支付信息）
+  - 内置标签模板（商品名称、价格、条码）
+  - 变量替换和条件渲染
+  - 模板验证功能
+
+- **条码生成器 (BarcodeGenerator)** - 多格式条码支持
+  - Code128、Code39、EAN-13、EAN-8、UPC-A 格式
+  - 条码内容验证
+  - 可配置高度、宽度、文字位置
+
+- **文本格式化器 (TextFormatter)** - ESC/POS 文本格式化
+  - 对齐方式（左/中/右）
+  - 字体缩放（1-8倍）
+  - 粗体、下划线、反白样式
+
+- **预览渲染器 (PreviewRenderer)** - 打印预览功能
+  - ESC/POS 命令解析
+  - 渲染为 Base64 图像
+  - 支持文本、条码、二维码预览
+
+- **Web Bluetooth 适配器 (WebBluetoothAdapter)** - H5 环境支持
+  - 浏览器兼容性检测
+  - 设备请求和选择
+  - 完整的连接/断开/写入功能
+
+- **连接稳定性增强**
+  - 心跳检测机制
+  - 自动重连（可配置重试次数和间隔）
+  - 自适应传输参数（动态调整分片大小和延迟）
+
+- **BluetoothPrinter 新方法**
+  - `align(alignment)` - 设置文本对齐
+  - `setSize(width, height)` - 设置字体大小
+  - `setBold(enabled)` - 设置粗体
+  - `setUnderline(enabled)` - 设置下划线
+  - `resetStyle()` - 重置样式
+  - `barcode(content, format, options)` - 打印条码
+
+- **编码服务 (EncodingService)** - 完整的中文编码支持
+  - GBK、GB2312、Big5、UTF-8 编码
+  - 编码自动检测
+  - 不支持字符的替代处理
+
+### Changed
+
+- 更新了 `src/index.ts`，导出所有新模块
+- 更新了 `AdapterFactory`，支持 Web Bluetooth 平台
+- 增强了 `ConnectionManager`，支持心跳和自动重连
+- 更新了 API 文档和 README，添加新功能说明
+
+### Fixed
+
+- 修复了格式化相关的 lint 错误
+
 ## [2.1.2] - 2025-12-16
 
 ### Added

package/README.md

@@ -21,9 +21,16 @@
 - 🎨 **简洁 API** - 链式调用，易于使用
 - 🖼️ **图片打印** - 内置 Floyd-Steinberg 抖动算法，高质量图片转换
 - 📲 **二维码支持** - 原生 ESC/POS 二维码指令
+- 📊 **条码支持** - 支持 Code128、Code39、EAN-13、EAN-8、UPC-A 格式
 - 🔄 **断点续传** - 支持打印任务暂停/恢复/取消
-- 📶 **弱网适配** - 智能分片与重试机制
+- 📶 **弱网适配** - 智能分片与重试机制，自适应传输参数
 - 📊 **进度追踪** - 实时打印进度事件
+- 💾 **离线缓存** - 断网时自动缓存，重连后自动同步
+- 📋 **打印队列** - 优先级排序，失败自动重试
+- 📝 **模板引擎** - 内置收据和标签模板
+- 🔍 **打印预览** - ESC/POS 命令渲染为图像预览
+- 🌐 **Web Bluetooth** - 支持 H5 环境的 Web Bluetooth API
+- 💓 **连接稳定** - 心跳检测和自动重连机制
 - 🛠️ **TypeScript** - 完整的类型定义和 JSDoc 文档
 - 🧪 **高测试覆盖** - 76%+ 代码覆盖率
 
@@ -113,12 +120,7 @@ const printer = new BluetoothPrinter();
 await printer.connect(deviceId);
 
 // 构建大量打印内容
-printer
-  .text('第1页内容...')
-  .feed(10)
-  .text('第2页内容...')
-  .feed(10)
-  .text('第3页内容...');
+printer.text('第1页内容...').feed(10).text('第2页内容...').feed(10).text('第3页内容...');
 
 // 开始打印（异步）
 const printPromise = printer.print();
@@ -155,11 +157,8 @@ Taro.canvasGetImageData({
   height: 100,
   success: res => {
     const imageData = new Uint8Array(res.data);
-    
-    printer
-      .image(imageData, res.width, res.height)
-      .feed(2)
-      .print();
+
+    printer.image(imageData, res.width, res.height).feed(2).print();
   },
 });
 ```
@@ -169,14 +168,84 @@ Taro.canvasGetImageData({
 ```typescript
 // 配置重试和分片参数
 printer.setOptions({
-  chunkSize: 20,     // 每次发送20字节
-  delay: 30,         // 分片间延迟30ms
-  retries: 5,        // 失败重试5次
+  chunkSize: 20, // 每次发送20字节
+  delay: 30, // 分片间延迟30ms
+  retries: 5, // 失败重试5次
 });
 
 await printer.text('测试内容').print();
 ```
 
+### 文本格式化 (v2.2+)
+
+```typescript
+await printer
+  .align('center')
+  .setSize(2, 2)
+  .setBold(true)
+  .text('大标题')
+  .resetStyle()
+  .feed()
+  .align('left')
+  .text('正常文本')
+  .print();
+```
+
+### 条码打印 (v2.2+)
+
+```typescript
+await printer.text('商品条码：').barcode('6901234567890', 'EAN13', { height: 80 }).feed(2).print();
+```
+
+### 设备管理 (v2.2+)
+
+```typescript
+import { DeviceManager } from 'taro-bluetooth-print';
+
+const deviceManager = new DeviceManager();
+
+// 监听设备发现
+deviceManager.on('device-found', device => {
+  console.log('发现设备:', device.name, device.deviceId);
+});
+
+// 开始扫描
+await deviceManager.startScan({ timeout: 10000 });
+
+// 获取已发现的设备
+const devices = deviceManager.getDiscoveredDevices();
+```
+
+### 打印队列 (v2.2+)
+
+```typescript
+import { PrintQueue } from 'taro-bluetooth-print';
+
+const queue = new PrintQueue({ maxSize: 100 });
+
+// 添加高优先级任务
+queue.add(printData, { priority: 'HIGH' });
+
+// 监听完成事件
+queue.on('job-completed', job => {
+  console.log('任务完成:', job.id);
+});
+```
+
+### 离线缓存 (v2.2+)
+
+```typescript
+import { OfflineCache } from 'taro-bluetooth-print';
+
+const cache = new OfflineCache();
+
+// 断网时自动缓存
+await cache.save({ id: 'job-1', data: printData });
+
+// 重连后同步
+await cache.sync();
+```
+
 ## 📚 文档
 
 完整文档请访问：**[https://agions.github.io/taro-bluetooth-print/](https://agions.github.io/taro-bluetooth-print/)**
@@ -192,59 +261,73 @@ await printer.text('测试内容').print();
 
 ### BluetoothPrinter
 
-| 方法 | 说明 | 返回值 |
-|------|------|--------|
-| `connect(deviceId)` | 连接蓝牙设备 | `Promise<this>` |
-| `disconnect()` | 断开连接 | `Promise<void>` |
-| `text(content, encoding?)` | 添加文本 | `this` |
-| `feed(lines?)` | 换行 | `this` |
-| `image(data, width, height)` | 打印图片 | `this` |
-| `qr(content, options?)` | 打印二维码 | `this` |
-| `cut()` | 切纸 | `this` |
-| `setOptions(options)` | 设置适配器参数 | `this` |
-| `print()` | 发送打印 | `Promise<void>` |
-| `pause()` | 暂停打印 | `void` |
-| `resume()` | 恢复打印 | `Promise<void>` |
-| `cancel()` | 取消打印 | `void` |
-| `remaining()` | 获取剩余字节数 | `number` |
+| 方法                                 | 说明                 | 返回值          |
+| ------------------------------------ | -------------------- | --------------- |
+| `connect(deviceId)`                  | 连接蓝牙设备         | `Promise<this>` |
+| `disconnect()`                       | 断开连接             | `Promise<void>` |
+| `text(content, encoding?)`           | 添加文本             | `this`          |
+| `feed(lines?)`                       | 换行                 | `this`          |
+| `image(data, width, height)`         | 打印图片             | `this`          |
+| `qr(content, options?)`              | 打印二维码           | `this`          |
+| `barcode(content, format, options?)` | 打印条码 (v2.2+)     | `this`          |
+| `align(alignment)`                   | 设置对齐 (v2.2+)     | `this`          |
+| `setSize(width, height)`             | 设置字体大小 (v2.2+) | `this`          |
+| `setBold(enabled)`                   | 设置粗体 (v2.2+)     | `this`          |
+| `setUnderline(enabled)`              | 设置下划线 (v2.2+)   | `this`          |
+| `resetStyle()`                       | 重置样式 (v2.2+)     | `this`          |
+| `cut()`                              | 切纸                 | `this`          |
+| `setOptions(options)`                | 设置适配器参数       | `this`          |
+| `print()`                            | 发送打印             | `Promise<void>` |
+| `pause()`                            | 暂停打印             | `void`          |
+| `resume()`                           | 恢复打印             | `Promise<void>` |
+| `cancel()`                           | 取消打印             | `void`          |
+| `remaining()`                        | 获取剩余字节数       | `number`        |
+| `qr(content, options?)`              | 打印二维码           | `this`          |
+| `cut()`                              | 切纸                 | `this`          |
+| `setOptions(options)`                | 设置适配器参数       | `this`          |
+| `print()`                            | 发送打印             | `Promise<void>` |
+| `pause()`                            | 暂停打印             | `void`          |
+| `resume()`                           | 恢复打印             | `Promise<void>` |
+| `cancel()`                           | 取消打印             | `void`          |
+| `remaining()`                        | 获取剩余字节数       | `number`        |
 
 ### 事件
 
-| 事件名 | 数据类型 | 说明 |
-|--------|---------|------|
-| `state-change` | `PrinterState` | 连接状态变化 |
-| `progress` | `{ sent, total }` | 打印进度 |
-| `error` | `BluetoothPrintError` | 错误事件 |
-| `connected` | `string` (deviceId) | 已连接 |
-| `disconnected` | `string` (deviceId) | 已断开 |
-| `print-complete` | `void` | 打印完成 |
+| 事件名           | 数据类型              | 说明         |
+| ---------------- | --------------------- | ------------ |
+| `state-change`   | `PrinterState`        | 连接状态变化 |
+| `progress`       | `{ sent, total }`     | 打印进度     |
+| `error`          | `BluetoothPrintError` | 错误事件     |
+| `connected`      | `string` (deviceId)   | 已连接       |
+| `disconnected`   | `string` (deviceId)   | 已断开       |
+| `print-complete` | `void`                | 打印完成     |
 
 ## 🔧 配置选项
 
 ```typescript
 interface IAdapterOptions {
-  chunkSize?: number;  // 分片大小（默认: 20字节）
-  delay?: number;      // 分片延迟（默认: 20ms）
-  retries?: number;    // 重试次数（默认: 3）
+  chunkSize?: number; // 分片大小（默认: 20字节）
+  delay?: number; // 分片延迟（默认: 20ms）
+  retries?: number; // 重试次数（默认: 3）
 }
 
 interface IQrOptions {
-  model?: 1 | 2;                        // 二维码模型（默认: 2）
-  size?: number;                        // 模块大小 1-16（默认: 6）
-  errorCorrection?: 'L'|'M'|'Q'|'H';   // 纠错级别（默认: 'M'）
+  model?: 1 | 2; // 二维码模型（默认: 2）
+  size?: number; // 模块大小 1-16（默认: 6）
+  errorCorrection?: 'L' | 'M' | 'Q' | 'H'; // 纠错级别（默认: 'M'）
 }
 ```
 
 ## 🌐 平台支持
 
-| 平台 | 支持情况 | 说明 |
-|------|---------|------|
-| 微信小程序 | ✅ | 完全支持 |
-| H5 | ✅ | 需要浏览器支持 Web Bluetooth |
-| React Native | ✅ | 通过 Taro RN |
-| 支付宝小程序 | ✅ | 完全支持 |
-| 百度小程序 | ✅ | 完全支持 |
-| 字节跳动小程序 | ✅ | 完全支持（抖音、头条等）
+| 平台           | 支持情况 | 说明                         |
+| -------------- | -------- | ---------------------------- |
+| 微信小程序     | ✅       | 完全支持                     |
+| H5             | ✅       | 需要浏览器支持 Web Bluetooth |
+| React Native   | ✅       | 通过 Taro RN                 |
+| 支付宝小程序   | ✅       | 完全支持                     |
+| 百度小程序     | ✅       | 完全支持                     |
+| 字节跳动小程序 | ✅       | 完全支持（抖音、头条等）     |
 
 ## 🏗️ 架构设计