更新记录

1.0（2025-06-03）

主要特性

1. 跨平台支持 - 同时支持Android和iOS
2. 完整的蓝牙功能 - 扫描、连接、数据传输
3. 丰富的打印功能 - 文本、二维码、小票模板
4. 类型安全 - 完整的TypeScript类型定义
5. 易于使用 - 简洁的API设计

核心功能

平台兼容性

uni-app(4.01)

uni-app x(4.01)

UTS 蓝牙打印机插件

这是一个基于 UTS (UniApp TypeScript) 开发的蓝牙连接和打印插件，支持 Android 和 iOS 平台。

功能特性

• ✅ 蓝牙设备扫描和连接
• ✅ 文本打印（支持对齐和字体大小设置）
• ✅ 二维码打印
• ✅ 小票打印模板
• ✅ 切纸功能
• ✅ 开钱箱功能
• ✅ 原始数据发送
• ✅ 连接状态管理
• ✅ 跨平台支持（Android/iOS）

安装使用

1. 将插件复制到项目中

将整个插件文件夹复制到你的 uni-app 项目的 uni_modules 目录下。

2. 配置权限

Android 权限

插件会自动添加以下权限：

• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.BLUETOOTH_SCAN
• android.permission.BLUETOOTH_CONNECT
• android.permission.BLUETOOTH_ADVERTISE

iOS 权限

在 Info.plist 中添加蓝牙使用说明： ```xml

```

3. 基本使用

```typescript import { bluetoothPrinter, BluetoothDeviceInfo, ConnectionState, PrintAlign, FontSize } from '@/uni_modules/uni-bluetooth-printer'

// 检查蓝牙状态 const isAvailable = bluetoothPrinter.isBluetoothAvailable() const isEnabled = bluetoothPrinter.isBluetoothEnabled()

// 扫描设备 bluetoothPrinter.startDiscovery((devices: BluetoothDeviceInfo[]) => { console.log('发现设备:', devices) })

// 连接设备 bluetoothPrinter.connect('设备地址', (success: boolean, error?: string) => { if (success) { console.log('连接成功') } else { console.log('连接失败:', error) } })

// 打印文本 bluetoothPrinter.printText('Hello World!', PrintAlign.CENTER, FontSize.LARGE)

// 打印二维码 bluetoothPrinter.printQRCode('https://example.com', 6)

// 打印小票 const orderData = { storeName: '示例商店', orderNo: 'ORDER123', items: [ { name: '商品A', quantity: 2, price: 15.50 } ], total: 31.00, paymentMethod: '微信支付', time: new Date().toLocaleString() } bluetoothPrinter.printReceipt(orderData) ```

API 文档

基础方法

isBluetoothAvailable(): boolean

检查设备是否支持蓝牙功能。

isBluetoothEnabled(): boolean

检查蓝牙是否已启用。

enableBluetooth(): boolean

启用蓝牙（仅 Android）。

getPairedDevices(): BluetoothDeviceInfo[]

获取已配对的蓝牙设备列表。

startDiscovery(callback: (devices: BluetoothDeviceInfo[]) => void): boolean

开始扫描蓝牙设备。

stopDiscovery(): boolean

停止扫描蓝牙设备。

connect(address: string, callback: (success: boolean, error?: string) => void): void

连接指定地址的蓝牙设备。

disconnect(): boolean

断开当前蓝牙连接。

isConnected(): boolean

检查是否已连接到蓝牙设备。

打印方法

printText(text: string, align?: PrintAlign, fontSize?: FontSize): boolean

打印文本内容。

参数：

• text: 要打印的文本
• align: 对齐方式（LEFT/CENTER/RIGHT）
• fontSize: 字体大小（NORMAL/LARGE/EXTRA_LARGE）

printNewLine(lines?: number): boolean

打印换行。

printDivider(char?: string, length?: number): boolean

打印分割线。

printQRCode(content: string, size?: number): boolean

打印二维码。

cutPaper(): boolean

切纸。

openCashDrawer(): boolean

开钱箱。

printReceipt(orderData: OrderData): boolean

打印小票。

数据类型

BluetoothDeviceInfo

```typescript interface BluetoothDeviceInfo { name: string // 设备名称 address: string // 设备地址 rssi?: number // 信号强度 paired: boolean // 是否已配对 } ```

ConnectionState

```typescript enum ConnectionState { DISCONNECTED = 0, // 未连接 CONNECTING = 1, // 连接中 CONNECTED = 2, // 已连接 DISCONNECTING = 3 // 断开中 } ```

PrintAlign

```typescript enum PrintAlign { LEFT = 0, // 左对齐 CENTER = 1, // 居中 RIGHT = 2 // 右对齐 } ```

FontSize

```typescript enum FontSize { NORMAL = 0, // 正常 LARGE = 1, // 大号 EXTRA_LARGE = 2 // 特大号 } ```

注意事项

1. 权限申请: Android 6.0+ 需要动态申请位置权限才能扫描蓝牙设备
2. 设备兼容性: 插件主要适用于 ESC/POS 协议的热敏打印机
3. 连接稳定性: 建议在连接前先停止设备扫描
4. 错误处理: 所有异步操作都提供了错误回调，请妥善处理
5. 资源释放: 应用退出时记得断开蓝牙连接

常见问题

Q: Android 扫描不到设备？

A: 检查是否已授予位置权限，Android 6.0+ 扫描蓝牙需要位置权限。

Q: iOS 连接失败？

A: 确保在 Info.plist 中添加了蓝牙使用说明，并且用户已授权。

Q: 打印内容乱码？

A: 检查打印机是否支持 UTF-8 编码，部分老式打印机可能需要 GBK 编码。

Q: 打印机不响应？

A: 确认打印机支持 ESC/POS 指令集，检查连接是否稳定。

更新日志

v1.0.0

• 初始版本发布
• 支持基础蓝牙连接和打印功能
• 支持 Android 和 iOS 平台

许可证

MIT License

Vue 2 和 Vue 3 兼容性

本插件同时支持 Vue 2 和 Vue 3，提供了两种不同的示例实现：

Vue 2 示例

使用 Options API 风格的实现，位于 example/bluetooth-printer-demo.vue。

Vue 3 示例

使用 Composition API 风格的实现，位于 example/bluetooth-printer-demo-vue3.vue。

使用说明

1. 对于 Vue 2 项目，直接使用 bluetooth-printer-demo.vue 作为参考
2. 对于 Vue 3 项目，可以使用 bluetooth-printer-demo-vue3.vue 作为参考
3. 核心插件代码对两个版本均兼容，无需修改

注意：在 Vue 2 项目中使用回调函数时，需要注意 this 的绑定问题，建议使用变量保存 this 引用或使用箭头函数。