微信小程序蓝牙打印技术实现全解析

一、蓝牙打印技术基础与适用场景

蓝牙打印技术通过短距离无线通信实现移动设备与打印机的数据传输，在微信小程序场景中主要应用于餐饮外卖小票打印、物流面单打印、零售收银凭证等轻量级打印需求。相较于传统有线打印方案，蓝牙打印具有部署灵活、成本低廉的优势，尤其适合中小商户快速实现移动端打印功能。

技术实现层面，微信小程序通过wx.openBluetoothAdapter、wx.startBluetoothDevicesDiscovery等API构建完整的蓝牙通信链路。开发者需要重点关注设备兼容性（支持BLE 4.0及以上协议）、数据格式转换（ESC/POS指令集处理）以及多设备并发管理三大技术要点。

二、核心API实现详解

1. 蓝牙适配器初始化

// 初始化蓝牙模块
wx.openBluetoothAdapter({
  success: (res) => {
    console.log('蓝牙适配器初始化成功', res)
    // 检查蓝牙状态
    wx.getBluetoothAdapterState({
      success: (stateRes) => {
        if (!stateRes.available) {
          wx.showModal({
            title: '提示',
            content: '当前设备不支持蓝牙功能'
          })
        }
      }
    })
  },
  fail: (err) => {
    console.error('蓝牙初始化失败', err)
    // 处理常见错误：10001-未授权，10002-系统拒绝
    if (err.errCode === 10001) {
      wx.openSetting({
        success: (settingRes) => {
          if (settingRes.authSetting['scope.bluetooth']) {
            wx.openBluetoothAdapter()
          }
        }
      })
    }
  }
})

2. 设备发现与过滤

// 启动设备发现（带服务过滤）
wx.startBluetoothDevicesDiscovery({
  services: ['0000FFF0-0000-1000-8000-00805F9B34FB'], // 常见打印机服务UUID
  allowDuplicatesKey: false,
  success: (discoveryRes) => {
    // 监听设备发现事件
    wx.onBluetoothDeviceFound((devicesRes) => {
      const devices = devicesRes.devices.filter(
        device => device.name && device.name.includes('Printer')
      )
      // 更新设备列表
      this.setData({ foundDevices: devices })
    })
  }
})

3. 建立稳定连接

// 创建BLE连接（带超时处理）
const connectWithTimeout = (deviceId, timeout = 5000) => {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      reject(new Error('连接超时'))
    }, timeout)
    wx.createBLEConnection({
      deviceId,
      success: (connRes) => {
        clearTimeout(timer)
        // 获取服务列表
        wx.getBLEDeviceServices({
          deviceId,
          success: (servicesRes) => {
            const targetService = servicesRes.services.find(
              service => service.uuid === '0000FFF0-0000-1000-8000-00805F9B34FB'
            )
            if (targetService) {
              resolve(targetService)
            } else {
              reject(new Error('未找到打印机服务'))
            }
          }
        })
      },
      fail: (err) => {
        clearTimeout(timer)
        reject(err)
      }
    })
  })
}

三、打印数据传输优化

1. 数据格式转换

// ESC/POS指令封装示例
class ESCPOSBuilder {
  constructor() {
    this.buffer = []
  }
  initialize() {
    this.buffer.push(0x1B, 0x40) // 初始化打印机
    return this
  }
  setAlignment(align) {
    // 0-左对齐 1-居中 2-右对齐
    const code = 0x1B + (align || 0)
    this.buffer.push(0x1B, 0x61, code)
    return this
  }
  printText(text) {
    // 处理中文编码（需根据打印机实际支持情况调整）
    const encoded = this.encodeGBK(text)
    this.buffer.push(...encoded)
    return this
  }
  cutPaper() {
    this.buffer.push(0x1D, 0x56, 0x41, 0x10) // 完整切纸
    return this
  }
  build() {
    return new Uint8Array(this.buffer)
  }
  // 简化的GBK编码实现（实际项目建议使用专业编码库）
  encodeGBK(str) {
    const result = []
    for (let i = 0; i < str.length; i++) {
      const charCode = str.charCodeAt(i)
      if (charCode < 0x80) {
        result.push(charCode)
      } else {
        // 简化的双字节编码处理
        result.push(0xD0 + Math.floor(charCode / 256))
        result.push(0xA0 + (charCode % 256))
      }
    }
    return result
  }
}

2. 特征值写入优化

// 分块写入大数据（解决MTU限制）
async function writeLargeData(deviceId, serviceId, characteristicId, data) {
  const CHUNK_SIZE = 20 // 根据实际设备MTU调整
  let offset = 0
  while (offset < data.length) {
    const chunk = data.slice(offset, offset + CHUNK_SIZE)
    try {
      await wx.writeBLECharacteristicValue({
        deviceId,
        serviceId,
        characteristicId,
        value: chunk.buffer
      })
      offset += CHUNK_SIZE
      // 添加适当延迟（根据设备响应速度调整）
      await new Promise(resolve => setTimeout(resolve, 50))
    } catch (err) {
      console.error('写入失败', err)
      throw err
    }
  }
}

四、异常处理与状态管理

1. 连接状态维护

// 使用状态机管理蓝牙生命周期
class BluetoothManager {
  constructor() {
    this.state = 'disconnected' // disconnected, connecting, connected
    this.deviceId = null
  }
  async connect(deviceId) {
    if (this.state === 'connecting') {
      throw new Error('连接进行中')
    }
    this.state = 'connecting'
    try {
      await connectWithTimeout(deviceId)
      this.deviceId = deviceId
      this.state = 'connected'
      return true
    } catch (err) {
      this.state = 'disconnected'
      throw err
    }
  }
  disconnect() {
    if (this.state !== 'connected') return
    return new Promise((resolve) => {
      wx.closeBLEConnection({
        deviceId: this.deviceId,
        success: () => {
          this.state = 'disconnected'
          this.deviceId = null
          resolve()
        }
      })
    })
  }
}

2. 常见错误处理方案

错误码	错误信息	处理方案
10001	未授权蓝牙权限	引导用户开启权限
10002	系统拒绝蓝牙操作	检查设备蓝牙是否开启
10003	蓝牙适配器不可用	提示用户检查硬件
10004	设备未找到	扩大搜索范围或重试
10005	连接失败	检查设备是否被占用

五、性能优化建议

1. 连接复用机制：建立设备连接池，避免频繁创建/销毁连接
2. 数据预处理：将常用打印模板缓存为指令数组
3. 异步队列管理：实现打印任务队列，防止并发冲突
4. 心跳检测：定期发送空指令保持连接活跃
5. 错误重试策略：对可恢复错误实施指数退避重试

六、完整实现示例

// 完整打印流程示例
class PrinterService {
  constructor() {
    this.bluetoothManager = new BluetoothManager()
    this.currentDevice = null
  }
  async printReceipt(deviceInfo, orderData) {
    try {
      // 1. 连接设备
      await this.bluetoothManager.connect(deviceInfo.deviceId)
      this.currentDevice = deviceInfo
      // 2. 构建打印数据
      const builder = new ESCPOSBuilder()
        .initialize()
        .setAlignment(1)
        .printText('=== 订单凭证 ===\n')
        .setAlignment(0)
        .printText(`订单号: ${orderData.id}\n`)
        .printText(`时间: ${new Date().toLocaleString()}\n`)
        .printText(`商品: ${orderData.items.join(',')}\n`)
        .printText(`总价: ¥${orderData.total}\n`)
        .cutPaper()
      const printData = builder.build()
      // 3. 获取特征值（实际项目需缓存）
      const servicesRes = await wx.getBLEDeviceServices({
        deviceId: deviceInfo.deviceId
      })
      const service = servicesRes.services.find(
        s => s.uuid === '0000FFF0-0000-1000-8000-00805F9B34FB'
      )
      const characteristicsRes = await wx.getBLEDeviceCharacteristics({
        deviceId: deviceInfo.deviceId,
        serviceId: service.uuid
      })
      const characteristic = characteristicsRes.characteristics.find(
        c => c.properties.write
      )
      // 4. 执行打印
      await writeLargeData(
        deviceInfo.deviceId,
        service.uuid,
        characteristic.uuid,
        printData
      )
      return { success: true }
    } catch (err) {
      console.error('打印失败', err)
      return {
        success: false,
        error: err.message || '未知错误'
      }
    } finally {
      // 保持连接或断开（根据业务需求）
      // await this.bluetoothManager.disconnect()
    }
  }
}

七、测试与验证要点

1. 多设备兼容性测试：覆盖主流打印机品牌（佳博、汉印、芯烨等）
2. 异常场景测试：
   • 打印过程中断开蓝牙
   • 发送超长数据（>20KB）
   • 低电量状态打印
3. 性能基准测试：
   • 首次连接耗时（建议<3s）
   • 打印响应时间（建议<1s/页）
   • 连续打印稳定性（100次无故障）

通过系统化的技术实现和严谨的测试验证，开发者可以构建出稳定可靠的微信小程序蓝牙打印方案。实际项目开发中，建议结合具体硬件特性进行参数调优，并建立完善的错误监控体系。