taro-bluetooth-print 2.2.1 → 2.3.1

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,342 +19,195 @@
 ## ✨ 特性
 
 - 🚀 **高性能** - 直接字节缓冲区操作，服务缓存优化
-- 📱 **跨平台** - 基于 Taro 蓝牙 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
-- 💓 **连接稳定** - 心跳检测和自动重连机制
-- 🛠️ **TypeScript** - 完整的类型定义和 JSDoc 文档
-- 🧪 **高测试覆盖** - 76%+ 代码覆盖率
+- 🔍 **打印预览** - ESC/POS 命令渲染为图像
+- 🔌 **插件系统** - 可扩展架构，支持自定义钩子
+- 🛠️ **TypeScript** - 完整的类型定义和 JSDoc
 
 ## 📦 安装
 
 ```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();
-```
-
-## 📚 文档
-
-完整文档请访问：**[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`        |
-
-### 事件
-
-| 事件名           | 数据类型              | 说明         |
-| ---------------- | --------------------- | ------------ |
-| `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                 |
-| 支付宝小程序   | ✅       | 完全支持                     |
-| 百度小程序     | ✅       | 完全支持                     |
-| 字节跳动小程序 | ✅       | 完全支持（抖音、头条等）     |
-
-## 🏗️ 架构设计
+## 🏗️ 架构
 
 ```
-┌─────────────────────────────────────┐
-│      BluetoothPrinter (Core)        │
-│  - 连接管理                          │
-│  - 打印队列                          │
-│  - 事件系统                          │
-│  - 断点续传                          │
-└────────┬────────────────┬───────────┘
-         │                │
-    ┌────▼─────┐    ┌────▼──────┐
-    │ Adapter  │    │  Driver   │
-    │  层      │    │   层      │
-    └──────────┘    └───────────┘
-         │                │
-    ┌────▼─────┐    ┌────▼──────┐
-    │Taro      │    │ESC/POS    │
-    │Adapter   │    │Driver     │
-    └──────────┘    └───────────┘
+┌─────────────────────────────────────────────────┐
+│            BluetoothPrinter (Core)              │
+│  - 连接管理  - 打印队列  - 事件系统  - 断点续传  │
+└──────────┬──────────────────┬───────────────────┘
+           │                  │
+     ┌─────▼──────┐     ┌────▼──────┐
+     │  Adapter   │     │  Driver   │
+     │    层      │     │    层     │
+     └────────────┘     └───────────┘
+           │                  │
+     ┌─────▼──────┐     ┌────▼──────┐     ┌────────────┐
+     │ Taro       │     │ ESC/POS   │     │  Plugin    │
+     │ Web BT     │     │ TSPL      │     │  System    │
+     │ 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
@@ -377,7 +232,9 @@ npm run docs:dev
 
 ## 🙏 致谢
 
-感谢所有贡献者的支持！
+- [Taro](https://taro.jd.com/) - 跨平台开发框架
+- [ESC/POS](https://www.epson-biz.com/) - 打印机指令集
+- 所有贡献者和测试用户
 
 ---