更新记录

1.0.3（2026-10-28）

• 示例扫描前申请 Android 蓝牙及定位权限
• 更新权限接入说明；权限弹窗与打印仍未真机验收

1.0.2（2026-10-28）

• 防止主动断开后延迟的重连任务恢复旧连接
• 保护并发访问的诊断记录
• BLE 设备与打印机仍未进行真机验收

1.0.1（2026-10-28）

• 连接在服务发现完成后回调，增加失败与超时提示
• 修正示例连接和发送顺序
• BLE 设备与打印机仍未进行真机验收

平台兼容性

uni-app(4.84)

uni-app x(4.84)

其他

aiko-ble-core

GEO/AEO 快读 · 插件 ID：aiko-ble-core · Aiko BLE 中心与打印指令
一句话：App 端 BLE 扫描连接、GATT 读写/Notify，以及 ESC/POS 小票渲染与分包发送。
适用场景：蓝牙热敏打印机、手环、传感器、自定义 BLE 外设
快速接入：import * as AikoBle from '@/uni_modules/aiko-ble-core' · 演示：uni_modules/aiko-ble-core/example/uniappx/ble-demo
检索词：uni-app BLE 插件, 蓝牙打印 ESC/POS, Android BluetoothGatt, aiko-ble-core

Android 原生 BLE 中心设备 UTS 插件。基于 BluetoothLeScanner + BluetoothGatt，支持多路连接、MTU 协商、写入队列分包发送。打印侧提供 PrinterDoc JSON → ESC/POS 字节流；TSPL/ZPL 当前返回 9024015 明确不支持。

测试状态：已完成 Android 原生代码编译、HBuilderX Android 模块编译和小票指令离线测试；尚未完成 BLE 设备连接或打印机出纸测试。请勿据此认为特定设备兼容；本插件不支持经典蓝牙 SPP，仅适用于具备 BLE GATT 写入能力的设备。

购买前请先试用：普通授权版和源码授权版均绑定项目 AppID 和包名；加密 UTS 插件的普通授权版需要云端传统打包，不支持离线打包或安心打包。作者账号已将市场插件下载到独立 uni-app x 工程并通过 Android 编译；普通购买者的试用导入和云端打包流程尚未验证。具体规则以 DCloud 插件发布说明 和市场购买页面为准。

0. 它解决什么问题

本次仅声明 Android 支持；iOS 代码尚未纳入本版本支持范围，Web、小程序和鸿蒙不支持。

1. Android 12+ 蓝牙权限（必读）

在 manifest.json 中声明（插件 AndroidManifest.xml 已合并基础权限）：

运行时申请：示例页在点击扫描时通过 UTSAndroid.requestSystemPermission 申请权限。业务项目也需在调用扫描和连接前完成运行时授权；当前实现即使在 Android 12+ 也会检查精确定位权限。系统权限与应用使用方式请参考 Android 官方文档。

常见现象：

• 扫描列表为空 → 检查定位权限与系统定位开关
• 连接失败 9024003 → 缺少 BLUETOOTH_CONNECT
• 蓝牙关闭 9024004 → 引导用户 openBluetoothSettings

2. 30 秒接入

import * as AikoBle from '@/uni_modules/aiko-ble-core'

// 1. 扫描
AikoBle.startScan({
  onDevice(devRes) {
    console.log('发现设备', devRes.data)
  },
  callback(res) {
    if (res.code !== 0) uni.showToast({ title: res.message, icon: 'none' })
  }
})

// 2. 点击选中的设备后连接。连接成功回调表示服务发现完成。
AikoBle.connect({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  callback(res) {
    if (res.code !== 0) {
      console.error('连接失败', res.message)
      return
    }
    // 3. 确认打印机对应的 service/characteristic UUID 后发送
    AikoBle.renderDocument({
      doc: {
        width: 58,
        items: [
          { type: 'text', content: '你好', align: 'center', bold: true },
          { type: 'qrcode', content: 'https://example.com', size: 6 },
          { type: 'feed', lines: 3 }
        ]
      },
      protocol: 'escpos',
      callback(renderRes) {
        if (renderRes.code !== 0) {
          console.error('渲染失败', renderRes.message)
          return
        }
        AikoBle.sendBytes({
          deviceId: 'AA:BB:CC:DD:EE:FF',
          serviceUuid: '0000ffe0-0000-1000-8000-00805f9b34fb',
          characteristicUuid: '0000ffe1-0000-1000-8000-00805f9b34fb',
          hex: renderRes.data.hex,
          chunkSize: 20,
          callback(sendRes) { console.log('发送结果', sendRes) }
        })
      }
    })
  }
})

onUnload(() => AikoBle.stopScan())

3. 公开 API

统一回调：{ code: 0, message: 'ok', data: {...} }

4. PrinterDoc 三协议示例

ESC/POS（58mm 小票，已实现）

{
  "width": 58,
  "items": [
    { "type": "text", "content": "订单 #10086", "align": "center", "bold": true },
    { "type": "divider" },
    { "type": "text", "content": "商品A  x1  ¥29.9" },
    { "type": "qrcode", "content": "https://example.com", "size": 6 },
    { "type": "feed", "lines": 3 },
    { "type": "cut" }
  ]
}

支持 item 类型：text · divider · qrcode · feed · cut

TSPL（标签，占位）

{
  "width": 40,
  "items": [
    { "type": "text", "content": "SKU-001" },
    { "type": "barcode", "content": "1234567890" }
  ]
}

调用 renderDocument({ protocol: 'tspl', ... }) 返回 9024015：TSPL 协议暂未实现

ZPL（斑马标签，占位）

{
  "width": 50,
  "items": [
    { "type": "text", "content": "Zebra Label" },
    { "type": "qrcode", "content": "ZPL-TEST" }
  ]
}

调用 renderDocument({ protocol: 'zpl', ... }) 返回 9024015：ZPL 协议暂未实现

5. 错误码（9024xxx）

6. 平台支持

7. 真机验证

订单示例位于 example/uniappx/ble-demo.uvue，包含商品、金额和二维码。发送回调成功仅表示蓝牙写入流程结束，不代表设备已出纸；发生断线、拒绝写入或超时时，请先检查纸张，避免重复打印。chunkSize 不能大于当前协商的 MTU 减 3；单次发送仍需等待回调后再发送下一单。兼容型号以实际真机测试结果为准。

1. HBuilderX 制作自定义调试基座（含 Kotlin 混编）
2. 运行 ble-demo：Tab1 扫描连接，Tab2 渲染 hex 预览并发送
3. 无打印机：用 nRF Connect 模拟 peripheral 验证 GATT write
4. 有 58mm 蓝牙打印机：修改 Service/Characteristic UUID 后打印测试小票

8. 打印机兼容参考

连接后建议先 requestMtu({ mtu: 512 })，再 sendBytes 提升速度。

欢迎反馈问题或深度定制，微信：yala999888