taro-bluetooth-print 1.0.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Your Name
+Copyright (c) 2025 Agions
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE. 
+SOFTWARE. 

package/README.md

@@ -2,25 +2,89 @@
 
 一个基于 Taro.js 的跨平台蓝牙打印库，支持微信小程序、H5、React Native 和鸿蒙等多平台，支持 ESC/POS 指令，可用于连接蓝牙打印机并发送打印数据。
 
-## 特性
-
-- 支持多平台：微信小程序、H5、React Native、鸿蒙OS
-- 支持 ESC/POS 打印指令
-- 提供简洁易用的 API
-- 支持打印文本、图片、条形码、二维码、收据等
-- 支持文本格式化（对齐、加粗、下划线等）
-- 支持打印模板系统，便于重用
-- TypeScript 支持
-
-## 安装
+<p align="center">
+  <img src="https://img.shields.io/npm/v/taro-bluetooth-print" alt="npm version">
+  <img src="https://img.shields.io/npm/l/taro-bluetooth-print" alt="license">
+  <img src="https://img.shields.io/npm/dt/taro-bluetooth-print" alt="downloads">
+</p>
+
+## 📑 目录
+
+- [特性](#特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [详细使用示例](#详细使用示例)
+  - [基本使用](#基本使用)
+  - [打印文本](#打印文本)
+  - [打印图片](#打印图片)
+  - [打印收据](#打印收据)
+  - [打印条形码](#打印条形码)
+  - [打印二维码](#打印二维码)
+  - [使用打印模板](#使用打印模板)
+- [配置项](#配置项)
+- [平台支持](#平台支持)
+- [常见问题](#常见问题)
+- [实际应用场景](#实际应用场景)
+- [API 文档](#api-文档)
+- [贡献指南](#贡献指南)
+- [许可证](#许可证)
+
+## ✨ 特性
+
+- 🌐 **多平台支持**：微信小程序、H5、React Native、鸿蒙OS
+- 🖨️ **完整的 ESC/POS 支持**：兼容大多数热敏打印机
+- 🔌 **简洁的 API**：易于使用的接口设计
+- 📄 **多样化打印内容**：文本、图片、条形码、二维码、收据等
+- 🎨 **文本格式化**：支持对齐、加粗、下划线等多种格式
+- 📋 **模板系统**：内置打印模板，方便重用
+- 📱 **TypeScript 支持**：完整的类型定义
+
+## 📦 安装
 
 ```bash
+# 使用 npm
 npm install taro-bluetooth-print --save
-# 或
+
+# 使用 yarn
 yarn add taro-bluetooth-print
+
+# 使用 pnpm
+pnpm add taro-bluetooth-print
+```
+
+## 🚀 快速开始
+
+只需几行代码，即可实现打印功能：
+
+```typescript
+import Taro from '@tarojs/taro';
+import TaroBluePrint from 'taro-bluetooth-print';
+
+// 初始化打印库
+const printer = new TaroBluePrint();
+
+// 连接打印机并打印
+async function printDemo() {
+  // 初始化蓝牙
+  await printer.bluetooth.init();
+  
+  // 连接到打印机（示例ID，实际使用时需要先扫描获取）
+  const connected = await printer.bluetooth.connect('你的打印机ID');
+  
+  if (connected) {
+    // 打印文本
+    await printer.printer.printText('Hello, Taro Print!');
+    
+    // 切纸并结束
+    await printer.printer.cut();
+    
+    // 断开连接
+    await printer.bluetooth.disconnect();
+  }
+}
 ```
 
-## 使用示例
+## 📝 详细使用示例
 
 ### 基本使用
 
@@ -94,22 +158,41 @@ scanAndConnect();
 ### 打印文本
 
 ```typescript
-await printer.printer.printText('Hello, World!', {
-  align: 'center',
-  bold: true,
-  doubleHeight: true
+// 基本文本打印
+await printer.printer.printText('Hello, World!');
+
+// 带格式的文本打印
+await printer.printer.printText('居中加粗大字体', {
+  align: 'center',   // 对齐方式: 'left' | 'center' | 'right'
+  bold: true,        // 是否加粗
+  doubleHeight: true, // 是否倍高
+  doubleWidth: false, // 是否倍宽
+  underline: false,  // 是否添加下划线
+  fontType: 'A'      // 字体类型: 'A' | 'B' | 'C'
 });
+
+// 打印多行文本
+await printer.printer.printText([
+  '第一行文本',
+  { text: '第二行加粗文本', bold: true },
+  { text: '第三行右对齐文本', align: 'right' }
+]);
 ```
 
 ### 打印图片
 
 ```typescript
+// 打印网络图片
 await printer.printer.printImage('https://example.com/logo.png', {
-  maxWidth: 300,
-  dithering: true
+  maxWidth: 300,     // 最大宽度（像素）
+  dithering: true    // 是否启用抖动算法（提高黑白图片质量）
 });
 
-// 或打印Base64图片
+// 打印本地图片（小程序）
+const tempFilePath = 'wxfile://temp-file-path';
+await printer.printer.printImage(tempFilePath);
+
+// 打印Base64图片
 await printer.printer.printImage('data:image/png;base64,...', {
   maxWidth: 300
 });
@@ -118,8 +201,9 @@ await printer.printer.printImage('data:image/png;base64,...', {
 ### 打印收据
 
 ```typescript
+// 打印简单收据
 await printer.printer.printReceipt({
-  title: '收据',
+  title: '消费小票',
   merchant: '示例商店',
   items: [
     { name: '商品1', price: 10.5, quantity: 2 },
@@ -130,23 +214,62 @@ await printer.printer.printReceipt({
   footer: '感谢您的惠顾，欢迎再次光临！',
   logo: 'https://example.com/logo.png' // 可选
 });
+
+// 打印带有更多信息的收据
+await printer.printer.printReceipt({
+  title: '消费小票',
+  merchant: '示例商店',
+  address: '北京市朝阳区xx路xx号',
+  phone: '010-12345678',
+  orderNo: 'ORD12345678',
+  items: [
+    { name: '商品1', price: 10.5, quantity: 2 },
+    { name: '商品2', price: 5.0, quantity: 1 },
+    { name: '商品3（八折优惠）', price: 20.0, quantity: 1, discount: 0.8 }
+  ],
+  subtotal: 41.0,
+  discount: 4.0,
+  tax: 3.7,
+  total: 40.7,
+  payment: {
+    method: '微信支付',
+    amount: 40.7
+  },
+  date: '2023-09-28 15:30:45',
+  operator: '收银员: 张三',
+  footer: '感谢您的惠顾，欢迎再次光临！\n请保留小票作为退换凭证',
+  qrcode: 'https://example.com/receipt/12345',
+  logo: 'https://example.com/logo.png'
+});
 ```
 
 ### 打印条形码
 
 ```typescript
+// 打印简单条形码
+await printer.printer.printBarcode('123456789');
+
+// 打印带有配置的条形码
 await printer.printer.printBarcode('123456789', {
-  height: 80,
-  align: 'center'
+  height: 80,           // 高度，默认为 80
+  width: 2,             // 宽度，默认为 2
+  position: 'below',    // 文本位置: 'none' | 'above' | 'below' | 'both'
+  align: 'center',      // 对齐方式: 'left' | 'center' | 'right'
+  type: 'EAN13'         // 条码类型: 'UPC-A' | 'UPC-E' | 'EAN13' | 'EAN8' | 'CODE39' | 'ITF' | 'CODABAR' | 'CODE93' | 'CODE128'
 });
 ```
 
 ### 打印二维码
 
 ```typescript
+// 打印简单二维码
+await printer.printer.printQRCode('https://example.com');
+
+// 打印带有配置的二维码
 await printer.printer.printQRCode('https://example.com', {
-  size: 8,
-  align: 'center'
+  size: 8,            // 尺寸因子 (1-16)，默认为 8
+  errorCorrection: 'M', // 纠错级别: 'L'(7%) | 'M'(15%) | 'Q'(25%) | 'H'(30%)
+  align: 'center'     // 对齐方式: 'left' | 'center' | 'right'
 });
 ```
 
@@ -173,29 +296,222 @@ const commands = await receiptTemplate.build();
 
 // 发送打印命令
 await printer.printer.sendCommands(commands);
+
+// 或者直接使用内置模板打印
+await printer.printer.printWithTemplate('receipt', {
+  title: '消费小票',
+  merchant: '示例商店',
+  // 其他数据...
+});
+```
+
+## ⚙️ 配置项
+
+### 初始化配置
+
+```typescript
+const printer = new TaroBluePrint({
+  debug: true,              // 是否开启调试模式，默认 false
+  encoding: 'GBK',          // 编码方式，支持 'GBK'、'UTF-8' 等，默认 'GBK'
+  characterSet: 'CHINA',    // 字符集，默认 'CHINA'
+  beep: false,              // 打印完成是否蜂鸣提示，默认 false
+  paperWidth: 58,           // 纸张宽度（mm），默认 58mm，支持 58/80mm
+  autoCut: true             // 打印完成是否自动切纸，默认 true
+});
 ```
 
-## API 文档
+### 蓝牙配置
 
-请查看完整的API文档以了解更多详情：[API文档](https://github.com/yourusername/taro-bluetooth-print/blob/main/docs/API.md)
+```typescript
+// 蓝牙扫描配置
+await printer.bluetooth.startDiscovery({
+  timeout: 10000,           // 扫描超时时间（毫秒），默认 10000ms
+  services: ['1812'],       // 要搜索的服务 UUID，默认打印服务 1812
+  allowDuplicatesKey: false // 是否允许重复上报设备，默认 false
+});
+```
 
-## 平台支持
+## 📱 平台支持
 
 | 功能 | 微信小程序 | H5 | React Native | 鸿蒙OS |
-| --- | --- | --- | --- | --- |
-| 设备扫描 | ✓ | ✓* | ✓ | ✓ |
-| 设备连接 | ✓ | ✓* | ✓ | ✓ |
-| 文本打印 | ✓ | ✓ | ✓ | ✓ |
-| 图片打印 | ✓ | ✓ | ✓ | ✓ |
-| 条码打印 | ✓ | ✓ | ✓ | ✓ |
-| 二维码打印 | ✓ | ✓ | ✓ | ✓ |
+| --- | :---: | :---: | :---: | :---: |
+| 设备扫描 | ✅ | ✅* | ✅ | ✅ |
+| 设备连接 | ✅ | ✅* | ✅ | ✅ |
+| 文本打印 | ✅ | ✅ | ✅ | ✅ |
+| 图片打印 | ✅ | ✅ | ✅ | ✅ |
+| 条码打印 | ✅ | ✅ | ✅ | ✅ |
+| 二维码打印 | ✅ | ✅ | ✅ | ✅ |
+
+> **注意**：H5 环境需要支持 Web Bluetooth API 的浏览器。目前 Chrome、Edge、Opera 等基于 Chromium 的浏览器支持此功能，且需要在 HTTPS 环境下使用。Safari 不支持 Web Bluetooth API。
+
+### 平台特殊配置
+
+#### 微信小程序
+
+需要在 `app.json` 中添加蓝牙相关权限：
+
+```json
+{
+  "permission": {
+    "scope.bluetooth": {
+      "desc": "请求获取蓝牙权限用于连接打印机"
+    }
+  }
+}
+```
+
+#### H5
+
+H5 环境下，需要用户主动触发蓝牙操作（如点击按钮），不能自动调用蓝牙 API。
+
+#### React Native
+
+需要安装依赖：
+
+```bash
+npm install react-native-ble-plx --save
+# 或
+yarn add react-native-ble-plx
+```
+
+且需要在 Android 和 iOS 项目中进行相关权限配置。
+
+## ❓ 常见问题
+
+### Q: 为什么连接不到打印机？
+
+A: 请检查以下几点：
+1. 确保打印机已开启并处于可发现模式
+2. 确保蓝牙已启用且权限已授予
+3. 检查设备与打印机之间的距离
+4. 尝试重启打印机
+5. 有些打印机可能需要配对，请先在系统设置中配对
+
+### Q: 为什么图片打印质量不佳？
+
+A: 图片打印质量受多种因素影响：
+1. 启用 `dithering: true` 选项可提高黑白图片质量
+2. 调整 `maxWidth` 为打印机支持的最佳宽度（一般为 384 像素或更小）
+3. 优先使用简单、清晰的图片，避免复杂的渐变和细节
+
+### Q: 打印中文出现乱码怎么办？
+
+A: 中文乱码通常是编码问题：
+1. 确保初始化时使用正确的编码，对于中文通常使用 'GBK'：
+   ```typescript
+   const printer = new TaroBluePrint({ encoding: 'GBK' });
+   ```
+2. 确保设置了正确的字符集：
+   ```typescript
+   await printer.printer.setCharacterSet('CHINA');
+   ```
+
+### Q: 在H5环境下无法使用怎么办？
+
+A:
+1. 确保使用支持 Web Bluetooth API 的浏览器（Chrome、Edge、Opera等）
+2. 确保在 HTTPS 环境下运行
+3. 蓝牙操作必须由用户交互触发（如点击按钮）
+4. 在某些操作系统（如macOS上的某些浏览器）可能存在限制
+
+## 🔍 实际应用场景
+
+### 零售小票打印
+
+适用于商店、超市、餐厅等需要打印购物小票、订单小票的场景。
+
+```typescript
+// 打印小票示例
+await printer.printer.printReceipt({
+  title: '消费小票',
+  merchant: '好又多超市',
+  address: '北京市海淀区中关村大街1号',
+  phone: '010-12345678',
+  orderNo: 'ORD20230928001',
+  items: [
+    { name: '牛奶 250ml', price: 4.5, quantity: 2 },
+    { name: '面包', price: 8.0, quantity: 1 },
+    { name: '水果', price: 15.8, quantity: 1 }
+  ],
+  subtotal: 32.8,
+  discount: 3.0,
+  total: 29.8,
+  payment: { method: '微信支付', amount: 29.8 },
+  date: new Date().toLocaleString(),
+  footer: '感谢您的惠顾，欢迎再次光临！'
+});
+```
+
+### 物流快递标签
+
+适用于物流公司、电商平台等需要打印快递标签的场景。
+
+```typescript
+// 打印快递标签
+await printer.printer.printText('顺丰速运', { align: 'center', bold: true, doubleHeight: true });
+await printer.printer.printLine();
+await printer.printer.printText('收件人: 张三');
+await printer.printer.printText('电话: 138****1234');
+await printer.printer.printText('地址: 北京市朝阳区xxx路xxx号');
+await printer.printer.printLine();
+await printer.printer.printBarcode('SF1234567890', { height: 80, position: 'below' });
+await printer.printer.printQRCode('SF1234567890');
+await printer.printer.cut();
+```
+
+### 会员卡及优惠券
+
+适用于商场、酒店、健身房等需要打印会员卡、优惠券的场景。
 
-*注意：H5 环境需要支持 Web Bluetooth API 的浏览器。目前 Chrome、Edge、Opera 等基于 Chromium 的浏览器支持此功能，且需要在 HTTPS 环境下使用。
+```typescript
+// 打印会员卡
+await printer.printer.printText('VIP会员卡', { align: 'center', bold: true, doubleHeight: true });
+await printer.printer.printImage('https://example.com/vip-logo.png', { maxWidth: 300 });
+await printer.printer.printText('会员姓名: 李四', { align: 'center' });
+await printer.printer.printText('会员等级: 金卡会员', { align: 'center' });
+await printer.printer.printText('有效期至: 2024-12-31', { align: 'center' });
+await printer.printer.printQRCode('https://example.com/member/12345');
+await printer.printer.printText('扫码查看会员权益', { align: 'center' });
+await printer.printer.cut();
+```
+
+## 📚 API 文档
+
+完整的 API 文档请参考：[API文档](docs/API.md)
+
+## 🤝 贡献指南
+
+非常欢迎您为 taro-bluetooth-print 项目贡献代码！以下是贡献的步骤：
+
+1. Fork 本仓库
+2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交您的修改 (`git commit -m 'Add some amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 打开一个 Pull Request
+
+### 开发环境设置
+
+```bash
+# 克隆仓库
+git clone https://github.com/Agions/taro-bluetooth-print.git
+
+# 安装依赖
+cd taro-bluetooth-print
+npm install
+
+# 运行构建
+npm run build
+```
 
-## 许可证
+### 贡献类型
 
-MIT
+您可以通过多种方式贡献：
+- 修复 bug
+- 添加新特性
+- 改进文档
+- 优化性能
+- 添加测试用例
 
-## 贡献
+## 📄 许可证
 
-欢迎提交 Issue 和 PR！
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

package/dist/bluetooth/index.d.ts

@@ -1,4 +1,8 @@
-import { BluetoothDevice } from './adapter';
+import { BluetoothDevice, ConnectOptions, DiscoveryOptions } from '../types';
+/**
+ * 蓝牙管理器类
+ * 负责蓝牙设备的扫描、连接和通信
+ */
 export declare class BluetoothManager {
     private adapter;
     private isInitialized;
@@ -7,6 +11,9 @@ export declare class BluetoothManager {
     private discoveredDevices;
     private serviceUUID;
     private characteristicUUID;
+    /**
+     * 创建蓝牙管理器实例
+     */
     constructor();
     /**
      * 初始化蓝牙模块
@@ -14,8 +21,9 @@ export declare class BluetoothManager {
     init(): Promise<boolean>;
     /**
      * 开始搜索蓝牙设备
+     * @param options 搜索选项
      */
-    startDiscovery(): Promise<boolean>;
+    startDiscovery(options?: DiscoveryOptions): Promise<boolean>;
     /**
      * 停止搜索蓝牙设备
      */
@@ -26,9 +34,10 @@ export declare class BluetoothManager {
     getDiscoveredDevices(): Promise<BluetoothDevice[]>;
     /**
      * 连接蓝牙设备
-     * @param deviceId 蓝牙设备ID
+     * @param deviceId 设备ID
+     * @param options 连接选项
      */
-    connect(deviceId: string): Promise<boolean>;
+    connect(deviceId: string, options?: ConnectOptions): Promise<boolean>;
     /**
      * 断开蓝牙连接
      */
@@ -38,6 +47,24 @@ export declare class BluetoothManager {
      * @param data 要写入的数据
      */
     writeData(data: ArrayBuffer): Promise<boolean>;
+    /**
+     * 检查是否已连接
+     */
+    isConnected(): boolean;
+    /**
+     * 获取已连接的设备ID
+     */
+    getConnectedDeviceId(): string | null;
+    /**
+     * 获取适配器初始化状态
+     */
+    getInitStatus(): boolean;
+    /**
+     * 设置服务和特征值UUID
+     * @param serviceUUID 服务UUID
+     * @param characteristicUUID 特征值UUID
+     */
+    setServiceUUIDs(serviceUUID: string, characteristicUUID: string): void;
     /**
      * 销毁蓝牙模块
      */