taro-bluetooth-print

Taro Bluetooth Print

轻量级、高性能的 Taro 蓝牙打印库
支持图片、二维码、断点续传与弱网适配

✨ 特性

• 🚀 高性能 - 直接字节缓冲区操作，服务缓存优化
• 📱 跨平台 - 基于 Taro 蓝牙 API，支持微信小程序、H5、React Native 等
• 🎨 简洁 API - 链式调用，易于使用
• 🖼️ 图片打印 - 内置 Floyd-Steinberg 抖动算法，高质量图片转换
• 📲 二维码支持 - 原生 ESC/POS 二维码指令
• 🔄 断点续传 - 支持打印任务暂停/恢复/取消
• 📶 弱网适配 - 智能分片与重试机制
• 📊 进度追踪 - 实时打印进度事件
• 🛠️ TypeScript - 完整的类型定义和 JSDoc 文档
• 🧪 高测试覆盖 - 76%+ 代码覆盖率

📦 安装

npm install taro-bluetooth-print
# 或
yarn add taro-bluetooth-print
# 或
pnpm add taro-bluetooth-print

🚀 快速开始

基础示例

import { BluetoothPrinter } from 'taro-bluetooth-print';

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();
  }
}

监听打印进度

import { BluetoothPrinter, LogLevel, Logger } from 'taro-bluetooth-print';

// 启用调试日志（可选）
Logger.setLevel(LogLevel.DEBUG);

const printer = new BluetoothPrinter();

// 监听进度
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('打印完成！');
});

await printer.connect(deviceId);
await printer.text('Hello').feed().print();

断点续传示例

const printer = new BluetoothPrinter();

await printer.connect(deviceId);

// 构建大量打印内容
printer
  .text('第1页内容...')
  .feed(10)
  .text('第2页内容...')
  .feed(10)
  .text('第3页内容...');

// 开始打印（异步）
const printPromise = printer.print();

// 5秒后暂停
setTimeout(() => {
  printer.pause();
  console.log('已暂停，剩余:', printer.remaining(), '字节');
}, 5000);

// 再过5秒恢复
setTimeout(async () => {
  await printer.resume();
  console.log('已恢复打印');
}, 10000);

await printPromise;

图片打印

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();
  },
});

弱网适配

// 配置重试和分片参数
printer.setOptions({
  chunkSize: 20,     // 每次发送20字节
  delay: 30,         // 分片间延迟30ms
  retries: 5,        // 失败重试5次
});

await printer.text('测试内容').print();

📚 文档

完整文档请访问：https://agions.github.io/taro-bluetooth-print/

• 安装指南
• 功能特性
• 核心概念
• 高级用法
• API 参考
• 故障排除

🎯 核心 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
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	打印完成

🔧 配置选项

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'）
}

🌐 平台支持

平台	支持情况	说明
微信小程序	✅	完全支持
H5	✅	需要浏览器支持 Web Bluetooth
React Native	✅	通过 Taro RN
支付宝小程序	⚠️	需要适配蓝牙 API
百度小程序	⚠️	需要适配蓝牙 API

🏗️ 架构设计

┌─────────────────────────────────────┐
│      BluetoothPrinter (Core)        │
│  - 连接管理                          │
│  - 打印队列                          │
│  - 事件系统                          │
│  - 断点续传                          │
└────────┬────────────────┬───────────┘
         │                │
    ┌────▼─────┐    ┌────▼──────┐
    │ Adapter  │    │  Driver   │
    │  层      │    │   层      │
    └──────────┘    └───────────┘
         │                │
    ┌────▼─────┐    ┌────▼──────┐
    │Taro      │    │ESC/POS    │
    │Adapter   │    │Driver     │
    └──────────┘    └───────────┘

• Core 层: 核心业务逻辑
• Adapter 层: 平台适配（Taro、Web Bluetooth 等）
• Driver 层: 打印机协议（ESC/POS、TSPL 等）

🤝 贡献

欢迎贡献！请查看 贡献指南。

开发设置

# 克隆仓库
git clone https://github.com/agions/taro-bluetooth-print.git
cd taro-bluetooth-print

# 安装依赖
npm install

# 运行测试
npm test

# 构建
npm run build

# 本地文档
npm run docs:dev

📄 许可证

MIT © Agions

🙏 致谢

感谢所有贡献者的支持！

Made with ❤️ by Agions