uni-app App端调用系统蓝牙打印机实现方法

先给出一个核心结论：在 uni-app App 端开发蓝牙打印功能时，你无法直接“调用系统蓝牙打印机”，因为 uni-app 本身并未提供统一的打印服务抽象层。要实现打印输出，必须走原生的 BLE 通信链路——手动连接设备、发现服务、然后写入 CPCL 或 ESC 指令。所谓的“调用系统”，本质上就是绕过系统自带的打印框架，直接与蓝牙设备建立连接并发送原始指令。

弄清楚这个前提后，我们再来看实际操作中的几个关键步骤。这些细节曾卡住过不少开发者，值得特别留意。

第一步：务必调用 uni.getBluetoothAdapterState，并在 success 回调中执行后续逻辑

如果跳过这一步，后果非常直接：在 iOS 上，90% 的连接会静默失败；在安卓上，你大概率会收到一个 errCode: 10001，或者干脆搜不到设备。它不是一个可选的检查项，而是所有后续操作必须通过的“前提闸门”。

• 当 res.available === false 时，应该提示用户去系统设置里开启蓝牙，比如用 uni.showToast({ title: '请前往手机设置开启蓝牙' })。只调用 uni.openBluetoothAdapter 是远远不够的。
• 如果 res.discovering === true，你需要先调用 uni.stopBluetoothDevicesDiscovery()，再重新调用 uni.startBluetoothDevicesDiscovery()，否则新的搜索不会触发 onBluetoothDeviceFound 回调。
• 在 iOS 上，首次运行时 res.poweredOff === true 是正常现象。因为蓝牙授权弹窗返回前的状态并不可靠，必须等回调落地后再采取行动。

第二步：服务和特征值的 UUID 绝不能硬编码

很多人喜欢把 00001101-0000-1000-8000-00805F9B34FB 这样的 UUID 直接写死在 getBLEDeviceCharacteristics 方法里。结果呢？连上了，但指令发不出去。为什么？因为 CPCL 打印机（比如芝柯 ZJ-5890）和 ESC/POS 打印机（比如驰腾 CT-320）对服务发现的顺序非常敏感。某些固件会故意隐藏标准的串口服务，或者要求你必须先发现通用访问服务（00001800-0000-1000-8000-00805F9B34FB）。

• 连接成功后，建议加一个 600–800ms 的 setTimeout 延迟（特别是红米 Note 系列），然后再调 uni.getBLEDeviceServices。
• 如果拿到的 res.services 是空的，说明服务还没加载完成，这时候应该尝试重连，而不是继续往下走。
• 在查找特征值时，只取那些 properties.write === true && properties.notify === false 的项。CPCL 是单向写入的，如果不小心选错了特征值，你会收到 errCode: 10009 的报错。

第三步：CPCL 指令必须用 \r\n 换行，并且要转成 ArrayBuffer 发送

这是很多人容易踩坑的地方。如果用 \n 或者漏掉了末尾的换行符，打印机大概率只会老老实实地打出第一行。另外，uni-app 的 writeBLECharacteristicValue 方法要求 value 是 ArrayBuffer 类型，如果你是直接传字符串，它只会静默地失败，不会给你任何提示。

• 正确的做法是：new TextEncoder().encode('TEXT 24 0 30 50 Hello\r\nBARCODE 128\r\n').buffer。
• 每次 write 前，必须校验一次连接状态。你可以使用 uni.getConnectedBluetoothDevices，或者监听 onBLEConnectionStateChange 事件，确保连状态是 connected: true。
• 如果指令很长（比如包含图片的 CPCL 指令），需要分段写入。单次写入的数据不要超过 20 字节（有些机型的限制更严格），并且每次写入间隔至少 20ms。

最后，再强调两个最容易忽略的细节：服务发现后的延迟空档，以及换行符的写法。很多时候，你以为设备“状态就绪”了，但实际上服务还未就绪；你以为 \n 就够了，但打印机只认 \r\n。这两个点，往往能卡住你大半个调试时间。