taro-bluetooth-print 2.3.0 → 2.4.0

package/README.md

@@ -4,12 +4,14 @@
   <img src="https://img.shields.io/npm/v/taro-bluetooth-print?style=flat-square&color=00d8ff" alt="npm version">
   <img src="https://img.shields.io/npm/dm/taro-bluetooth-print?style=flat-square&color=00d8ff" alt="downloads">
   <img src="https://img.shields.io/npm/l/taro-bluetooth-print?style=flat-square&color=00d8ff" alt="license">
-  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome">
+  <img src="https://img.shields.io/github/stars/agions/taro-bluetooth-print?style=flat-square" alt="stars">
+  <img src="https://img.shields.io/github/forks/agions/taro-bluetooth-print?style=flat-square" alt="forks">
+  <img src="https://img.shields.io/bundlephobia/minzip/taro-bluetooth-print?style=flat-square" alt="bundle size">
 </p>
 
 <p align="center">
   <strong>轻量级、高性能的 Taro 蓝牙打印库</strong><br>
-  支持图片、二维码、断点续传与弱网适配
+  支持热敏打印机、标签打印机，多平台适配
 </p>
 
 ---
@@ -17,421 +19,176 @@
 ## ✨ 特性
 
 - 🚀 **高性能** - 直接字节缓冲区操作，服务缓存优化
-- 📱 **跨平台** - 基于 Taro 4.x 蓝牙 API，支持微信小程序、H5、React Native 等
-- 🎨 **简洁 API** - 链式调用，易于使用
-- 🖼️ **图片打印** - 内置 Floyd-Steinberg 抖动算法，高质量图片转换
-- 📲 **二维码支持** - 原生 ESC/POS 二维码指令
-- 📊 **条码支持** - 支持 Code128、Code39、EAN-13、EAN-8、UPC-A 格式
-- 🔄 **断点续传** - 支持打印任务暂停/恢复/取消
-- 📶 **弱网适配** - 智能分片与重试机制，自适应传输参数
+- 📱 **多平台** - 微信小程序、H5、鸿蒙、支付宝、百度、字节跳动
+- 🎨 **多驱动** - ESC/POS (热敏)、TSPL/ZPL/CPCL (标签)
+- 🖼️ **图片打印** - 内置 Floyd-Steinberg 抖动算法
+- 📲 **二维码/条码** - 原生指令支持，多种格式，格式校验
+- 🔄 **断点续传** - 暂停/恢复/取消打印任务
+- 📶 **弱网适配** - 智能分片与重试机制
 - 📊 **进度追踪** - 实时打印进度事件
-- 💾 **离线缓存** - 断网时自动缓存，重连后自动同步
+- 💾 **离线缓存** - 断网自动缓存，联网自动同步
 - 📋 **打印队列** - 优先级排序，失败自动重试
 - 📝 **模板引擎** - 内置收据和标签模板
-- 🔍 **打印预览** - ESC/POS 命令渲染为图像预览
-- 🌐 **Web Bluetooth** - 支持 H5 环境的 Web Bluetooth API
-- 💓 **连接稳定** - 心跳检测和自动重连机制
-- 🏷️ **标签打印** - TSPL 协议支持，适用于 TSC 等标签打印机 (v2.3+)
-- 🔌 **插件系统** - 可扩展架构，支持自定义钩子 (v2.3+)
-- 🛠️ **TypeScript** - 完整的类型定义和 JSDoc 文档
-- 🧪 **高测试覆盖** - Vitest 驱动，69+ 测试用例
+- 🔍 **打印预览** - ESC/POS 命令渲染为图像
+- 🔌 **插件系统** - 可扩展架构，支持自定义钩子
+- 🛠️ **TypeScript** - 完整的类型定义和 JSDoc
+- 📡 **多打印机管理** - MultiPrinterManager 支持多设备并发
+- 💰 **配置持久化** - PrinterConfigManager 保存打印机配置
+- 📦 **批量打印优化** - BatchPrintManager 合并小任务减少开销
+- 📜 **打印历史** - PrintHistory 追踪打印记录和统计
+- 🖨️ **状态查询** - PrinterStatus 检测纸张/电量状态
 
 ## 📦 安装
 
 ```bash
+# npm
 npm install taro-bluetooth-print
-# 或
+
+# yarn
 yarn add taro-bluetooth-print
-# 或
+
+# pnpm
 pnpm add taro-bluetooth-print
 ```
 
-## 🚀 快速开始
-
-### 基础示例
+## 📊 性能
 
-```typescript
-import { BluetoothPrinter } from 'taro-bluetooth-print';
+| 指标 | 值 |
+|------|-----|
+| Bundle 大小 | **26 KB** (gzip) |
+| Tree-shaking | ✅ 支持 |
+| 按需加载 | ✅ 编码表懒加载 |
 
-const printer = new BluetoothPrinter();
+## 🚀 快速开始
 
-async function printReceipt(deviceId: string) {
-  try {
-    // 连接设备
-    await printer.connect(deviceId);
-
-    // 构建打印内容
-    await printer
-      .text('=== 欢迎光临 ===', 'GBK')
-      .feed()
-      .text('商品A     x1    ¥10.00')
-      .text('商品B     x2    ¥20.00')
-      .feed()
-      .text('------------------------')
-      .text('合计：            ¥30.00')
-      .feed(2)
-      .qr('https://example.com', { size: 8 })
-      .feed(2)
-      .cut()
-      .print(); // 发送到打印机
-
-    console.log('打印成功！');
-  } catch (error) {
-    console.error('打印失败:', error);
-  } finally {
-    await printer.disconnect();
+```typescript
+import { BluetoothPrinter, DeviceManager } from 'taro-bluetooth-print';
+
+async function print() {
+  // 1. 扫描设备
+  const manager = new DeviceManager();
+  await manager.startScan({ timeout: 10000 });
+  const devices = manager.getDiscoveredDevices();
+  
+  if (devices.length === 0) {
+    console.log('未发现设备');
+    return;
   }
+  
+  // 2. 连接打印机
+  const printer = new BluetoothPrinter();
+  await printer.connect(devices[0].deviceId);
+  
+  // 3. 打印
+  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')
+    .feed(2)
+    .cut()
+    .print();
+    
+  // 4. 断开
+  await printer.disconnect();
+  
+  console.log('打印完成！');
 }
 ```
 
-### 监听打印进度
+## 🖥️ 支持的平台
 
-```typescript
-import { BluetoothPrinter, LogLevel, Logger } from 'taro-bluetooth-print';
+| 平台 | 适配器 | 状态 |
+|------|--------|------|
+| 微信小程序 | `TaroAdapter` | ✅ |
+| H5 (Web Bluetooth) | `WebBluetoothAdapter` | ✅ |
+| 支付宝小程序 | `AlipayAdapter` | ✅ |
+| 百度小程序 | `BaiduAdapter` | ✅ |
+| 字节跳动小程序 | `ByteDanceAdapter` | ✅ |
+| 鸿蒙 HarmonyOS | `HarmonyOSAdapter` | ✅ |
+| React Native | `TaroAdapter` | ✅ |
 
-// 启用调试日志（可选）
-Logger.setLevel(LogLevel.DEBUG);
+## 🖨️ 支持的驱动
 
-const printer = new BluetoothPrinter();
+| 驱动 | 协议 | 适用打印机 |
+|------|------|-----------|
+| `EscPos` | ESC/POS | 热敏票据打印机 (58/80mm) |
+| `TsplDriver` | TSPL | TSC 标签打印机 |
+| `ZplDriver` | ZPL | Zebra 斑马标签打印机 |
+| `CpclDriver` | CPCL | HP/霍尼韦尔移动打印机 |
 
-// 监听进度
-printer.on('progress', ({ sent, total }) => {
-  const percent = ((sent / total) * 100).toFixed(1);
-  console.log(`打印进度: ${percent}%`);
-});
-
-// 监听错误
-printer.on('error', error => {
-  console.error('打印错误:', error.code, error.message);
-});
-
-// 监听完成
-printer.on('print-complete', () => {
-  console.log('打印完成！');
-});
+### 标签打印示例 (TSPL)
 
-await printer.connect(deviceId);
-await printer.text('Hello').feed().print();
-```
+```typescript
+import { BluetoothPrinter, TsplDriver } from 'taro-bluetooth-print';
 
-### 断点续传示例
+const driver = new TsplDriver();
+const printer = new BluetoothPrinter(undefined, driver);
 
-```typescript
-const printer = new BluetoothPrinter();
+driver
+  .size(60, 40)           // 60x40mm 标签
+  .gap(3)                 // 间隙 3mm
+  .clear()
+  .text('商品名称', { x: 20, y: 20, font: 3 })
+  .text('¥99.00', { x: 20, y: 60, font: 4 })
+  .barcode('6901234567890', { x: 20, y: 100, type: 'EAN13' })
+  .qrcode('https://example.com', { x: 250, y: 20 })
+  .print(1);
 
 await printer.connect(deviceId);
+await printer.print();
+```
 
-// 构建大量打印内容
-printer.text('第1页内容...').feed(10).text('第2页内容...').feed(10).text('第3页内容...');
+## 📚 示例项目
 
-// 开始打印（异步）
-const printPromise = printer.print();
+完整的示例项目，帮助快速上手：
 
-// 5秒后暂停
-setTimeout(() => {
-  printer.pause();
-  console.log('已暂停，剩余:', printer.remaining(), '字节');
-}, 5000);
+- [微信小程序示例](examples/weapp/) - 完整的打印页面
+- [H5 示例](examples/h5/) - Web Bluetooth 网页打印
+- [鸿蒙示例](examples/harmonyos/) - HarmonyOS 原生打印服务
+- [React Native 示例](examples/react-native/) - RN 打印组件
 
-// 再过5秒恢复
-setTimeout(async () => {
-  await printer.resume();
-  console.log('已恢复打印');
-}, 10000);
+## 📖 文档
 
-await printPromise;
-```
+- [快速开始](https://agions.github.io/taro-bluetooth-print/guide/getting-started) - 5 分钟入门
+- [功能特性](https://agions.github.io/taro-bluetooth-print/guide/features) - 全部功能介绍
+- [驱动支持](https://agions.github.io/taro-bluetooth-print/guide/drivers) - ESC/POS, TSPL, ZPL, CPCL
+- [核心概念](https://agions.github.io/taro-bluetooth-print/guide/core-concepts) - 架构设计与原理
+- [API 参考](https://agions.github.io/taro-bluetooth-print/api) - 完整的 API 文档
+- [故障排除](https://agions.github.io/taro-bluetooth-print/guide/troubleshooting) - 常见问题解决
 
-### 图片打印
+## 🔧 配置
 
 ```typescript
-import Taro from '@tarojs/taro';
-
-// 从 Canvas 获取图片数据
-const canvas = Taro.createCanvasContext('myCanvas');
-// ... 绘制内容 ...
-
-Taro.canvasGetImageData({
-  canvasId: 'myCanvas',
-  x: 0,
-  y: 0,
-  width: 200,
-  height: 100,
-  success: res => {
-    const imageData = new Uint8Array(res.data);
-
-    printer.image(imageData, res.width, res.height).feed(2).print();
-  },
-});
-```
-
-### 弱网适配
+const printer = new BluetoothPrinter();
 
-```typescript
-// 配置重试和分片参数
+// 适配器参数
 printer.setOptions({
-  chunkSize: 20, // 每次发送20字节
-  delay: 30, // 分片间延迟30ms
-  retries: 5, // 失败重试5次
+  chunkSize: 20,   // 分片大小 (默认 20)
+  delay: 20,       // 分片间隔 ms (默认 20)
+  retries: 3,      // 重试次数 (默认 3)
 });
 
-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);
+// 事件监听
+printer.on('progress', ({ sent, total }) => {
+  console.log(`进度: ${(sent / total * 100).toFixed(1)}%`);
 });
 
-// 开始扫描
-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);
+printer.on('error', (error) => {
+  console.error('错误:', error.code, error.message);
 });
-```
-
-### 离线缓存 (v2.2+)
-
-```typescript
-import { OfflineCache } from 'taro-bluetooth-print';
-
-const cache = new OfflineCache();
-
-// 断网时自动缓存
-await cache.save({ id: 'job-1', data: printData });
-
-// 重连后同步
-await cache.sync();
-```
-
-### TSPL 标签打印 (v2.3+)
 
-```typescript
-import { TsplDriver } from 'taro-bluetooth-print';
-
-const tspl = new TsplDriver();
-
-// 生成标签打印指令
-const buffer = tspl
-  .size(60, 40)           // 标签尺寸 60x40mm
-  .gap(3)                 // 标签间隙 3mm
-  .clear()                // 清除缓冲区
-  .text('商品名称', { x: 50, y: 30, font: 3 })
-  .text('¥99.00', { x: 50, y: 80, font: 4, xMultiplier: 2 })
-  .barcode('6901234567890', { 
-    x: 50, 
-    y: 120, 
-    type: 'EAN13',
-    height: 60 
-  })
-  .qrcode('https://example.com', { 
-    x: 300, 
-    y: 30, 
-    cellWidth: 4 
-  })
-  .print(1)               // 打印1份
-  .getBuffer();
-
-// 发送到打印机
-await printer.connect(deviceId);
-await printer.setOptions({ chunkSize: 100 });
-// 直接发送 TSPL 指令需要自定义适配器
-```
-
-### 插件系统 (v2.3+)
-
-```typescript
-import { 
-  PluginManager, 
-  createLoggingPlugin, 
-  createRetryPlugin 
-} from 'taro-bluetooth-print';
-
-// 创建插件管理器
-const plugins = new PluginManager();
-
-// 注册日志插件
-await plugins.register(createLoggingPlugin({
-  logProgress: true,  // 记录进度
-}));
-
-// 注册重试插件
-await plugins.register(createRetryPlugin({
-  maxRetries: 5,
-  initialDelay: 1000,
-}));
-
-// 自定义插件
-const myPlugin = {
-  name: 'my-plugin',
-  hooks: {
-    beforePrint: (buffer) => {
-      console.log(`即将打印 ${buffer.length} 字节`);
-      return buffer; // 可以修改数据
-    },
-    afterPrint: (bytesSent) => {
-      console.log(`打印完成: ${bytesSent} 字节`);
-    },
-    onError: (error) => {
-      // 上报错误
-      reportError(error);
-      return false; // false = 不抑制错误
-    },
-  },
-};
-
-await plugins.register(myPlugin);
-```
-
-## 📚 文档
-
-完整文档请访问：**[https://agions.github.io/taro-bluetooth-print/](https://agions.github.io/taro-bluetooth-print/)**
-
-- [安装指南](https://agions.github.io/taro-bluetooth-print/guide/getting-started)
-- [功能特性](https://agions.github.io/taro-bluetooth-print/guide/features)
-- [核心概念](https://agions.github.io/taro-bluetooth-print/guide/core-concepts)
-- [高级用法](https://agions.github.io/taro-bluetooth-print/guide/advanced)
-- [API 参考](https://agions.github.io/taro-bluetooth-print/api)
-- [故障排除](https://agions.github.io/taro-bluetooth-print/guide/troubleshooting)
-
-## 🎯 核心 API
-
-### BluetoothPrinter
-
-| 方法                                 | 说明                 | 返回值          |
-| ------------------------------------ | -------------------- | --------------- |
-| `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`        |
-
-### TsplDriver (v2.3+)
-
-| 方法                           | 说明               | 返回值       |
-| ------------------------------ | ------------------ | ------------ |
-| `size(width, height)`          | 设置标签尺寸(mm)   | `this`       |
-| `gap(gap, offset?)`            | 设置标签间隙       | `this`       |
-| `speed(speed)`                 | 设置打印速度(1-10) | `this`       |
-| `density(density)`             | 设置打印浓度(0-15) | `this`       |
-| `clear()`                      | 清除图像缓冲区     | `this`       |
-| `text(content, options)`       | 添加文本           | `this`       |
-| `barcode(content, options)`    | 添加条码           | `this`       |
-| `qrcode(content, options)`     | 添加二维码         | `this`       |
-| `box(options)`                 | 绘制矩形框         | `this`       |
-| `line(options)`                | 绘制线条           | `this`       |
-| `print(copies?, sets?)`        | 打印               | `this`       |
-| `getBuffer()`                  | 获取指令缓冲区     | `Uint8Array` |
-| `getCommands()`                | 获取指令字符串     | `string`     |
-
-### PluginManager (v2.3+)
-
-| 方法                        | 说明           | 返回值          |
-| --------------------------- | -------------- | --------------- |
-| `register(plugin, options)` | 注册插件       | `Promise<void>` |
-| `unregister(name)`          | 注销插件       | `Promise<void>` |
-| `get(name)`                 | 获取插件       | `Plugin`        |
-| `has(name)`                 | 检查插件是否存在 | `boolean`     |
-| `getNames()`                | 获取所有插件名 | `string[]`      |
-| `clear()`                   | 清除所有插件   | `Promise<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）
-}
-
-interface IQrOptions {
-  model?: 1 | 2; // 二维码模型（默认: 2）
-  size?: number; // 模块大小 1-16（默认: 6）
-  errorCorrection?: 'L' | 'M' | 'Q' | 'H'; // 纠错级别（默认: 'M'）
-}
+printer.on('print-complete', () => {
+  console.log('打印完成');
+});
 ```
 
-## 🌐 平台支持
-
-| 平台           | 支持情况 | 说明                         |
-| -------------- | -------- | ---------------------------- |
-| 微信小程序     | ✅       | 完全支持                     |
-| H5             | ✅       | 需要浏览器支持 Web Bluetooth |
-| React Native   | ✅       | 通过 Taro RN                 |
-| 支付宝小程序   | ✅       | 完全支持                     |
-| 百度小程序     | ✅       | 完全支持                     |
-| 字节跳动小程序 | ✅       | 完全支持（抖音、头条等）     |
-
-## 🏗️ 架构设计
+## 🏗️ 架构
 
 ```
 ┌─────────────────────────────────────────────────┐
@@ -447,26 +204,15 @@ interface IQrOptions {
      ┌─────▼──────┐     ┌────▼──────┐     ┌────────────┐
      │ Taro       │     │ ESC/POS   │     │  Plugin    │
      │ Web BT     │     │ TSPL      │     │  System    │
-     │ Alipay...  │     │ (ZPL...)  │     │  (v2.3+)   │
-     └────────────┘     └───────────┘     └────────────┘
-```
-         │                │
-    ┌────▼─────┐    ┌────▼──────┐
-    │Taro      │    │ESC/POS    │
-    │Adapter   │    │Driver     │
-    └──────────┘    └───────────┘
+     │ HarmonyOS │     │ ZPL       │     │  (v2.3+)   │
+     └────────────┘     │ CPCL      │     └────────────┘
+                        └───────────┘
 ```
 
-- **Core 层**: 核心业务逻辑
-- **Adapter 层**: 平台适配（Taro、Web Bluetooth 等）
-- **Driver 层**: 打印机协议（ESC/POS、TSPL 等）
-
 ## 🤝 贡献
 
 欢迎贡献！请查看 [贡献指南](./CONTRIBUTING.md)。
 
-### 开发设置
-
 ```bash
 # 克隆仓库
 git clone https://github.com/agions/taro-bluetooth-print.git
@@ -491,7 +237,9 @@ npm run docs:dev
 
 ## 🙏 致谢
 
-感谢所有贡献者的支持！
+- [Taro](https://taro.jd.com/) - 跨平台开发框架
+- [ESC/POS](https://www.epson-biz.com/) - 打印机指令集
+- 所有贡献者和测试用户
 
 ---