更新记录

1.0.0（2026-09-09）

• 初始版本
• 支持 Android 平台
• 支持 iOS 平台

平台兼容性

uni-app(4.72)

uni-app x(4.72)

zy-btprint 蓝牙打印插件

uni-app x 蓝牙打印 UTS 插件，支持 Android 和 iOS 平台，提供搜索、连接、发送数据、监听状态等功能。

功能特性

• ✅ 检查蓝牙状态
• ✅ 搜索蓝牙设备
• ✅ 获取已配对设备
• ✅ 连接蓝牙设备
• ✅ 发送十六进制数据
• ✅ 断开连接
• ✅ 监听连接状态

支持平台

安装

在 HBuilderX 插件市场搜索 zy-btprint 安装，或手动将插件目录复制到项目的 uni_modules/ 下。

权限配置

Android

插件已自动配置 AndroidManifest.xml，包含以下权限：

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS

插件已自动配置 config.json，包含以下权限：

{
  "frameworks": ["CoreBluetooth"],
  "plist": {
    "NSBluetoothAlwaysUsageDescription": "需要蓝牙权限来连接和控制蓝牙打印机",
    "NSBluetoothPeripheralUsageDescription": "需要蓝牙权限来连接和控制蓝牙打印机"
  }
}

API 说明

1. isBluetoothEnabled - 检查蓝牙状态

检查设备蓝牙是否已开启。

import { isBluetoothEnabled } from '@/uni_modules/zy-btprint'

isBluetoothEnabled({
  success: (res) => {
    console.log('蓝牙状态:', res.data.enabled)
  },
  fail: (err) => {
    console.error('检查失败:', err.errMsg)
  }
})

success 回调参数：

2. getPairedDevices - 获取已配对设备

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

import { getPairedDevices } from '@/uni_modules/zy-btprint'

getPairedDevices({
  success: (res) => {
    const devices = res.data.devices as Array<any>
    devices.forEach(device => {
      console.log('设备名:', device.deviceName)
      console.log('设备地址:', device.deviceAddress)
    })
  },
  fail: (err) => {
    console.error('获取失败:', err.errMsg)
  }
})

success 回调参数：

设备信息字段：

3. startDiscovery - 搜索蓝牙设备

开始搜索附近的蓝牙设备。

import { startDiscovery, stopDiscovery } from '@/uni_modules/zy-btprint'

startDiscovery({
  onEvent: (res) => {
    const event = res.event
    if (event === 'device_found') {
      const device = res.data.device
      console.log('发现设备:', device.deviceName)
    } else if (event === 'discovery_finished') {
      console.log('搜索完成')
    }
  },
  success: (res) => {
    console.log('搜索已开始')
  },
  fail: (err) => {
    console.error('搜索失败:', err.errMsg)
  }
})

// 停止搜索
stopDiscovery({
  callback: (res) => {
    console.log('搜索已停止')
  }
})

onEvent 回调事件：

4. connect - 连接蓝牙设备

连接指定的蓝牙设备。

import { connect } from '@/uni_modules/zy-btprint'

connect({
  deviceAddress: 'XX:XX:XX:XX:XX:XX', // 设备地址
  timeout: 8000, // 连接超时时间（毫秒），默认 8000
  success: (res) => {
    console.log('连接成功:', res.data)
  },
  fail: (err) => {
    console.error('连接失败:', err.errMsg)
  },
  complete: (res) => {
    console.log('连接操作完成')
  }
})

参数说明：

5. sendHex - 发送十六进制数据

向已连接的蓝牙设备发送十六进制数据。

import { sendHex } from '@/uni_modules/zy-btprint'

// 发送初始化命令
const initCmd = '1B40' // 示例：初始化打印机

sendHex({
  data: initCmd,
  success: (res) => {
    console.log('发送成功')
    console.log('发送的数据:', res.data.hex)
    console.log('字节数:', res.data.bytes)
  },
  fail: (err) => {
    console.error('发送失败:', err.errMsg)
  }
})

参数说明：

success 回调参数：

6. disconnect - 断开连接

断开当前蓝牙设备连接。

import { disconnect } from '@/uni_modules/zy-btprint'

disconnect({
  callback: (res) => {
    console.log('断开成功')
  }
})

7. reset - 重置初始化

重置蓝牙状态，停止搜索并断开连接。

import { reset } from '@/uni_modules/zy-btprint'

reset({
  callback: (res) => {
    console.log('重置成功')
  }
})

完整示例

<template>
  <view class="container">
    <button @click="checkBluetooth">检查蓝牙</button>
    <button @click="searchDevices">搜索设备</button>
    <button @click="connectPrinter">连接打印机</button>
    <button @click="printTest">打印测试</button>
    <button @click="disconnectPrinter">断开连接</button>

    <view class="device-list">
      <view v-for="device in devices" :key="device.deviceAddress" class="device-item">
        <text>{{ device.deviceName }}</text>
        <text>{{ device.deviceAddress }}</text>
        <button @click="connectDevice(device)">连接</button>
      </view>
    </view>
  </view>
</template>

<script>
import { 
  isBluetoothEnabled, 
  startDiscovery, 
  stopDiscovery,
  connect, 
  sendHex, 
  disconnect,
  getPairedDevices 
} from '@/uni_modules/zy-btprint'

export default {
  data() {
    return {
      devices: [],
      isConnected: false,
      printerAddress: ''
    }
  },
  methods: {
    checkBluetooth() {
      isBluetoothEnabled({
        success: (res) => {
          if (res.data.enabled) {
            uni.showToast({ title: '蓝牙已开启' })
          } else {
            uni.showToast({ title: '请开启蓝牙', icon: 'none' })
          }
        }
      })
    },

    searchDevices() {
      this.devices = []
      startDiscovery({
        onEvent: (res) => {
          if (res.event === 'device_found') {
            this.devices.push(res.data.device)
          }
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      })
    },

    connectDevice(device) {
      stopDiscovery({})
      this.printerAddress = device.deviceAddress

      connect({
        deviceAddress: device.deviceAddress,
        timeout: 8000,
        success: (res) => {
          this.isConnected = true
          uni.showToast({ title: '连接成功' })
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      })
    },

    printTest() {
      if (!this.isConnected) {
        uni.showToast({ title: '请先连接打印机', icon: 'none' })
        return
      }

      // ESC/POS 初始化命令
      const initCmd = '1B40'
      // 设置居中
      const centerCmd = '1B6101'
      // 打印文本
      const textCmd = '48656C6C6F20576F726C64' // "Hello World" 的十六进制
      // 换行
      const newLine = '0A'
      // 切纸命令
      const cutCmd = '1D5601'

      sendHex({
        data: initCmd + centerCmd + textCmd + newLine + cutCmd,
        success: (res) => {
          uni.showToast({ title: '打印成功' })
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      })
    },

    disconnectPrinter() {
      disconnect({
        callback: (res) => {
          this.isConnected = false
          uni.showToast({ title: '已断开' })
        }
      })
    }
  },

  onUnload() {
    // 页面卸载时断开连接
    disconnect({})
  }
}
</script>

<style>
.container {
  padding: 20rpx;
}

button {
  margin: 20rpx 0;
}

.device-list {
  margin-top: 40rpx;
}

.device-item {
  padding: 20rpx;
  border-bottom: 1rpx solid #eee;
  display: flex;
  justify-content: space-between;
  align-items: center;
}
</style>

错误码

注意事项

1. iOS 限制：iOS 无法获取已配对设备列表，需要用户手动搜索并连接
2. 蓝牙权限：首次使用需要用户授权蓝牙权限
3. 后台限制：iOS 后台模式下蓝牙功能可能受限
4. 设备过滤：搜索结果会自动过滤无名称的设备
5. 连接超时：建议设置 8-15 秒的连接超时时间

更新日志

0.1.0

• 初始版本
• 支持 Android 平台
• 支持 iOS 平台