微信小程序/uni-app 蓝牙打印开发教程和常见问题总结【文末附源码】

微信小程序/uni-app 蓝牙打印开发教程和常见问题总结【文末附源码】

1️⃣ 写在前面

由于业务需要，需要在应用中集成数据打印功能，由于项目是基于uni-app 开发并发布成微信小程序，查阅了官方的开发文档在技术上是可实现的。

同时在淘宝上咨询了蓝牙打印机的卖家，确认蓝牙打印机是否具备自定义开发的功能。最终选择了佳博的GP-2120-TU系列蓝牙打印机，支持标签模式和票据模式。

• 蓝牙打印机型号信息

2️⃣ 蓝牙连接流程

关于连接蓝牙的操作和API 微信小程序和uni-app 的API接口规范都是一样的，只不过微信小程序是挂载到wx 对象上，而uni-app则是挂载在了uni 对象上。使用uni-app开发的朋友可以直接使用微信的接口（前提是后期将项目发布到微信小程序平台），这里放一下各平台的API文档地址。

• 微信小程序—蓝牙低功耗 (Bluetooth Low Energy, BLE)
• uni-app 蓝牙API文档

🔴 注意：搜索蓝牙和连接了蓝牙是用的普通蓝牙接口，操作打印机（写操作）使用的是低功耗蓝牙接口，这里也就要求，蓝牙打印机设备支持低功耗蓝牙。

---

开始开发之前简单梳理一下连接蓝牙打印进行打印操作的流程图。后续的开发将围绕流程图展开。

3️⃣ 连接蓝牙设备

由于我们项目使用的是uni-app，所以后面的开发将遵循uni-app的语法和规范。不过在关键功能实现和程序执行流程（见上图）上二者是一样的。

🔶 3.1 初始化蓝牙模块

打开蓝牙适配器

其他蓝牙相关 API 必须在 uni.openBluetoothAdapter 调用之后使用。否则 API 会返回错误（errCode=10000）。

uni.openBluetoothAdapter({
  success(res) {
    console.log(res)
  }
})

注意事项：
🔴 windows系统编译运行到微信开发者工具时需要通过真机调试才能调用蓝牙功能；

🔴 需要手机开启蓝牙

🔴 Android8.0+系统需开启定位 虽然我也没高明白连接蓝牙为什么需要开启定位，但这点很重要，如果没有开启定位在后续搜索蓝牙的时候无法发现蓝牙设备，同时程序也不会报错。

🔶 3.2 获取蓝牙适配器状态

理论上这步可以省略，不过为了确保程序不错意外，还是按部就班，在搜索蓝牙之前确保本机蓝牙状态正确。

uni.getBluetoothAdapterState({
  success(res) {
    console.log(res)
  }
})
// 错误码返回ok 则表示蓝牙适配器状态正常

🔶 3.3搜索蓝牙设备

在步骤3.2的成功回调函数里调用uni.startBluetoothDevicesDiscovery 接口搜索附近可用的蓝牙设备。

uni.startBluetoothDevicesDiscovery({
  success(res) {
    console.log(res)
  }
})

开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源，请在搜索并连接到设备后调用 uni.stopBluetoothDevicesDiscovery 方法停止搜索。

🔶 3.4 列出所有发现的蓝牙设备列表

在步骤3.3 的成功回调里面使用uni.getBluetoothDevices 接口获取蓝牙模块生效期间所有已发现的蓝牙设备。包括已经和本机处于连接状态的设备。由于蓝牙搜索需要一定过程，因此可以设置一定的延迟时间再执行uni.getBluetoothDevices 接口。

uni.startBluetoothDevicesDiscovery({
  success: function(res) {
    console.log(res);
    setTimeout(function() {
      uni.getBluetoothDevices({
        success: function(res) {
          var devices = [];
          var num = 0;

          for (var i = 0; i < res.devices.length; ++i) {
            if (res.devices[i].name != "未知设备") {
              devices[num] = res.devices[i];
              num++;
            }
          }
           
          // 将发现的蓝牙设备存储起来，以下代码仅供参考 
          that.setData({
            list: devices,
            isScanning: false
          });
          uni.hideLoading();
          uni.stopPullDownRefresh();
          uni.stopBluetoothDevicesDiscovery({
            success: function(res) {
              console.log("停止搜索蓝牙");
            }
          });
        }
      });
    }, 5000);  
  }
});

🔴 如果没有发现需要连接的目标设备可以适当增加 setTimeout 的延迟时间。或者通过 uni.onBluetoothDeviceFound(CALLBACK) 接口监听寻找到新设备的事件。

uni.onBluetoothDeviceFound(function(devices) {
  var re = JSON.parse(JSON.stringify(devices));
  console.log(re.devices[0].name + "  " + re.devices[0].deviceId);
  let name = re.devices[0].name;
  if (name != "未知设备") {
    let deviceId = re.devices[0].deviceId;
    
    // 将发现的蓝牙设备存储起来，一下代码仅供参考
    that.devices.push({
      name: name,
      deviceId: deviceId,
      services: []
    });
  }
});

🔴 在找到目标设备之后请及时使用**uni.stopBluetoothDevicesDiscovery(OBJECT)**** 停止搜索**。

uni.stopBluetoothDevicesDiscovery({
  success(res) {
    console.log(res)
  }
})

🔶 3.5 通过界面暂时发现的蓝牙设备

<!-- 代码仅供参考：list为步骤3.4 发现的所有可用设备列表 -->
<view
  v-for="(item, index) in list"
  :key="index"
  :data-title="item.deviceId"
  :data-name="item.name"
  :data-advertisData="item.advertisServiceUUIDs"
  @tap="bindViewTap"
  class="item"
  hover-class="item_hover"
>
  <view style="font-size: 16px; color: #333;">{{ item.name }}</view>
  <view style="font-size: 16px; color: #333;">{{ item.deviceId }}</view>
  <view style="font-size: 10px">
    信号强度: {{ item.RSSI }}dBm 
  </view>
</view>

🔶 3.6 连接目标设备

连接低功耗蓝牙设备。
若APP在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需进行搜索操作。

注意这里使用的是低功耗蓝牙设备接口

uni.createBLEConnection({
  deviceId: e.currentTarget.dataset.title,  // 设备id
  success: function(res) {
    console.log(res);
    app.globalData.BLEInformation.deviceId = e.currentTarget.dataset.title;
    that.getSeviceId();
  },
  fail: function(e) {
    uni.showModal({
      title: "提示",
      content: "连接失败",
      showCancel: false
    });
    console.log(e);
    uni.hideLoading();
  },
  complete: function(e) {
    console.log(e);
  }
});

注意：
🔴 请保证尽量成对的调用 createBLEConnection 和 closeBLEConnection 接口。安卓如果多次调用 createBLEConnection 创建连接，有可能导致系统持有同一设备多个连接的实例，导致调用closeBLEConnection 的时候并不能真正的断开与设备的连接。

🔴 蓝牙连接随时可能断开，建议监听 uni.onBLEConnectionStateChange 回调事件，当蓝牙设备断开时按需执行重连操作

🔴 若对未连接的设备或已断开连接的设备调用数据读写操作的接口，会返回 10006 错误，建议进行重连操作

4️⃣ 操作打印机

🔶 4.1 打印机指令说明

通过第三章的一系列操作之后，如果成功和蓝牙打印机取得连接那么后面的操作就比较简单了。

操作打印机本质上就是通过**uni.writeBLECharacteristicValue(OBJECT)**** 接口向蓝牙设备****写指令**。

这里需要注意的是不同的打印机可能指令集不同。不过就我目前了解的情况来看市面上的小型蓝牙打印机主要分标签打印机和票据打印机两种。而则两种打印机指令集又有所区别。

🔴 标签打印机使用的是TSC指令集

• TSC指令集格式如下
  

🔴 票据打印机使用的是ESC指令集

• ESC指令集格式如下
  

🔶 4.2 指令封装

原始的指令集在操作上是非常不方便的，因此还需要对指令集做进一步的封装，以方便调用。通常打印机设备商会提供封装好的SDK文件，这里以TSC文本打印指令为例，简单介绍一下指令处理过程，文末提供的源码中有蓝牙打印机店家提供的完成SDK文件。

setText = function(x, y, font, x_, y_, str) { //打印文字
  data = "TEXT " + x + "," + y + ",\"" + font + "\"," + 0 + "," + x_ + "," + y_ + "," + "\"" +
    str + "\"\r\n"
};

封装的目的就是将文本和指令组合成一个完整的蓝牙打印机可识别的指令字符串

5️⃣界面参考和打印效果

以下界面由蓝牙打印机店家提供的微信小程序源码反编译为uni-app项目而来。同时修复了源码中会导致蓝牙连接失败的错误，仅测试，代码可完整运行，可成功操作标签打印机和票据打印机实现打印功能。

🔶 5.1 界面展示

🔶 5.2 打印效果展示

6️⃣ 源码获取

🔴 扫描二维码关注 对话框回复: uni打印 获取uni-app蓝牙打印机源码

🔴 扫描二维码关注 对话框回复: wx打印 获取 微信小程序 蓝牙打印机源码

---

(完)