uni-app蓝牙打印全攻略

2026-05-03 09:54:54作者：戚魁泉Nursing

一、行业痛点分析：零售与餐饮打印场景的常见问题

在零售和餐饮行业的日常运营中，打印功能看似简单，实则暗藏诸多挑战。以下是从业者最常遇到的痛点：

1.1 连接稳定性差

传统蓝牙打印方案常出现连接中断、设备搜索不到等问题，尤其在多设备同时运行的高峰期，严重影响出单效率。据统计，餐饮高峰期因打印问题导致的订单延迟率高达30%，直接影响顾客体验。

1.2 跨平台兼容性不足

iOS和Android系统对蓝牙权限管理机制不同，导致同一套打印代码在不同设备上表现差异大。部分Android设备需要手动开启定位权限才能搜索蓝牙设备，增加了操作复杂度。

1.3 格式排版混乱

不同型号打印机对指令集支持程度不一，常出现字体大小不一致、对齐错乱、二维码无法识别等问题。58mm和80mm纸宽的差异也容易导致打印内容被截断。

1.4 错误处理机制缺失

当打印机缺纸、电量不足或连接中断时，缺乏有效的重试和提示机制，导致订单信息丢失，给商家造成经济损失。

二、技术原理拆解：蓝牙通信协议与指令系统解析

2.1 蓝牙通信协议详解 🔧

蓝牙打印主要基于BLE（低功耗蓝牙）技术，其通信流程包括以下四个阶段：

适配器初始化：通过uni.openBluetoothAdapter()启动蓝牙模块，这是所有蓝牙操作的前提。
设备发现：调用uni.startBluetoothDevicesDiscovery()搜索周围蓝牙设备，需注意设置合适的服务UUID过滤。
连接建立：使用uni.createBLEConnection()与目标设备建立连接，连接成功后可获取设备的服务和特征值。
数据传输：通过uni.writeBLECharacteristicValue()向打印机的写入特征值发送打印指令，实现数据传输。

2.2 ESC/POS指令系统解析 📄

ESC/POS是绝大多数热敏打印机支持的指令集，通过特定的控制码实现对打印格式的控制。常用指令包括：

0x1B 0x40：初始化打印机
0x1B 0x61 0x01：居中对齐
0x1B 0x21 0x10：设置字体放大
0x0A：换行
0x1D 0x21 0x01：设置打印浓度

这些指令需要转换为Uint8Array格式后发送给打印机，不同品牌打印机可能存在细微差异，建议参考设备手册进行调整。

三、阶梯式实践指南：从基础连接到高级排版

3.1 三步实现蓝牙打印基础连接 📱

第一步：初始化蓝牙模块

// 初始化蓝牙模块
function initBluetooth() {
  return new Promise((resolve, reject) => {
    uni.openBluetoothAdapter({
      success: () => {
        console.log('蓝牙模块初始化成功');
        resolve();
      },
      fail: (err) => {
        console.error('蓝牙模块初始化失败', err);
        if (err.errCode === 10001) {
          uni.showToast({ title: '请开启蓝牙', icon: 'none' });
        }
        reject(err);
      }
    });
  });
}

第二步：搜索并连接打印机

// 搜索蓝牙设备
async function searchPrinters() {
  try {
    await initBluetooth();
    
    uni.startBluetoothDevicesDiscovery({
      services: ['0000FFE0-0000-1000-8000-00805F9B34FB'], // 常见打印服务UUID
      success: () => {
        console.log('开始搜索设备');
      }
    });
    
    // 监听设备发现事件
    uni.onBluetoothDeviceFound((res) => {
      const devices = res.devices;
      devices.forEach(device => {
        if (device.name && device.name.includes('Printer')) {
          console.log('找到打印机', device);
          connectPrinter(device.deviceId);
        }
      });
    });
  } catch (err) {
    console.error('搜索设备失败', err);
  }
}

// 连接打印机
function connectPrinter(deviceId) {
  uni.createBLEConnection({
    deviceId,
    success: () => {
      console.log('连接打印机成功');
      // 连接成功后获取服务和特征值
      getPrinterServices(deviceId);
    },
    fail: (err) => {
      console.error('连接打印机失败', err);
      uni.showToast({ title: '连接打印机失败', icon: 'none' });
    }
  });
}

第三步：发送打印数据

// 发送打印数据
function sendPrintData(deviceId, serviceId, characteristicId, data) {
  uni.writeBLECharacteristicValue({
    deviceId,
    serviceId,
    characteristicId,
    value: data,
    success: () => {
      console.log('打印数据发送成功');
      uni.showToast({ title: '打印成功', icon: 'success' });
    },
    fail: (err) => {
      console.error('打印数据发送失败', err);
      uni.showToast({ title: '打印失败', icon: 'none' });
    }
  });
}

3.2 打印数据格式化与高级排版

基础文本格式化

// 文本转字节
function textToBytes(text) {
  const encoder = new TextEncoder();
  return encoder.encode(text);
}

// 生成打印数据
function generatePrintData() {
  const buffer = [];
  
  // 初始化打印机
  buffer.push(0x1B, 0x40);
  
  // 居中对齐
  buffer.push(0x1B, 0x61, 0x01);
  
  // 标题
  buffer.push(...textToBytes("美食餐厅订单"));
  buffer.push(0x0A, 0x0A); // 换行
  
  // 恢复左对齐
  buffer.push(0x1B, 0x61, 0x00);
  
  // 订单内容
  buffer.push(...textToBytes("--------------------------------"));
  buffer.push(0x0A);
  buffer.push(...textToBytes("香辣牛肉面 x 1    ￥28.00"));
  buffer.push(0x0A);
  buffer.push(...textToBytes("可乐（中） x 1    ￥5.00"));
  buffer.push(0x0A);
  buffer.push(...textToBytes("--------------------------------"));
  buffer.push(0x0A);
  
  // 合计
  buffer.push(0x1B, 0x21, 0x10); // 字体放大
  buffer.push(...textToBytes("总计：￥33.00"));
  buffer.push(0x0A, 0x0A);
  
  // 切纸
  buffer.push(0x1D, 0x56, 0x00);
  
  return new Uint8Array(buffer).buffer;
}

58mm与80mm打印机参数对比

参数	58mm打印机	80mm打印机
打印宽度	约48mm	约72mm
每行字符数	32个英文字符	48个英文字符
适用场景	小型收据、外卖小票	详细订单、厨房单
纸张成本	较低	较高
兼容性	大部分设备支持	部分便携设备不支持

3.3 跨平台兼容性测试表

系统版本	蓝牙连接	打印稳定性	权限要求
iOS 12+	稳定	良好	需要位置权限
iOS 14+	稳定	良好	需要蓝牙权限
Android 6.0+	一般	一般	需要位置和存储权限
Android 10+	良好	良好	需要蓝牙和位置权限
Android 12+	良好	良好	需要精确位置权限

重要提示：在Android 6.0以上设备中，需要在Manifest文件中声明BLUETOOTH、BLUETOOTH_ADMIN、ACCESS_FINE_LOCATION权限，同时在运行时动态申请位置权限。

3.4 技术难点Q&A

Q: 为什么打印机搜索不到设备？
A: 可能原因有：1)蓝牙未开启；2)设备不在有效范围内；3)权限未授予；4)打印机未进入配对模式。建议先检查蓝牙状态和权限，重启打印机后重试。

Q: 打印内容出现乱码怎么办？
A: 乱码通常是由于字符编码不匹配导致的。确保使用正确的字符集（如GBK或UTF-8），并检查打印机是否支持该编码格式。可尝试使用0x1B 0x74 0x01指令切换字符集。

Q: 如何实现打印进度监听？
A: 可通过监听蓝牙特征值变化事件onBLECharacteristicValueChange来获取打印机的状态反馈，从而实现打印进度和完成状态的监听。

四、应急方案：确保打印系统可靠运行

4.1 离线缓存打印机制

在网络不稳定或打印机暂时不可用时，可将打印任务缓存到本地，待恢复后自动重试：

// 缓存打印任务
function cachePrintTask(task) {
  const tasks = uni.getStorageSync('printTasks') || [];
  tasks.push({
    id: Date.now(),
    data: task,
    timestamp: Date.now(),
    retryCount: 0
  });
  uni.setStorageSync('printTasks', tasks);
}

// 恢复打印任务
function restorePrintTasks() {
  const tasks = uni.getStorageSync('printTasks') || [];
  tasks.forEach(task => {
    if (task.retryCount < 3) {
      printTask(task.data).then(() => {
        // 打印成功后从缓存中移除
        removePrintTask(task.id);
      }).catch(() => {
        task.retryCount++;
        updatePrintTask(task);
      });
    }
  });
}

4.2 错误重试机制

实现智能重试策略，根据错误类型决定是否重试及重试间隔：

// 带重试机制的打印函数
function printWithRetry(data, maxRetries = 3, delay = 1000) {
  return new Promise((resolve, reject) => {
    let retries = 0;
    
    function attemptPrint() {
      sendPrintData(deviceId, serviceId, characteristicId, data)
        .then(() => {
          resolve();
        })
        .catch(err => {
          retries++;
          if (retries < maxRetries) {
            console.log(`打印失败，正在重试(${retries}/${maxRetries})`);
            setTimeout(attemptPrint, delay * retries); // 指数退避策略
          } else {
            reject(err);
          }
        });
    }
    
    attemptPrint();
  });
}