更新记录

1.0.2（2026-06-25） 下载此版本

新增支持vue2

1.0.1（2026-06-25） 下载此版本

1.0.1（2026-06-24）

• 支持低功耗蓝牙扫描、连接、发送、接收、断开
• 单例模式，跨页面自动保持连接状态
• 提供事件总线（on / off / once）
• 同时导出 Vue 3 组合式 API useBluetooth

平台兼容性

uni-app(5.0)

uni-app x(5.0)

其他

q-bluetooth

基于 uni-app 官方蓝牙 API 封装的低功耗蓝牙（BLE）插件，单例模式，跨页面保持连接。

特性

• ✅ 扫描附近 BLE 设备 / 实时去重列表
• ✅ 连接设备、自动发现服务与特征
• ✅ 发送数据（ArrayBuffer / hex 字符串）
• ✅ 接收数据（自动开启 notify / indicate）
• ✅ 断开 / 关闭适配器
• ✅ 全局单例 + 事件总线，任意页面 import 拿到的是同一份连接
• ✅ 自带 Vue 3 组合式 API useBluetooth
• ✅ 全平台：App、微信 / 支付宝 / 百度 / 字节 / QQ 小程序

安装

1. 把整个 uni_modules/q-bluetooth 目录放进项目根目录的 uni_modules/ 下，无需在 main.js 引入。
2. App 端需在 manifest.json → App模块配置 → 蓝牙 勾选；小程序需在小程序后台配置蓝牙能力。

快速上手

// 任意页面
import qBluetooth from '@/uni_modules/q-bluetooth'

// 1. 初始化蓝牙适配器
await qBluetooth.init()

// 2. 监听扫描结果（增量去重列表）
qBluetooth.on('deviceFound', (devices) => {
  console.log('附近设备：', devices)
})

// 3. 开始扫描
await qBluetooth.startScan()

// 4. 连接（自动发现服务、自动开启 notify）
await qBluetooth.connect(deviceId)

// 5. 监听接收的数据
qBluetooth.on('receive', ({ value, hex }) => {
  console.log('收到：', hex)
})

// 6. 发送数据（支持 hex 字符串 / ArrayBuffer / Uint8Array）
await qBluetooth.send('A1B2C3D4')

// 7. 断开
await qBluetooth.disconnect()

跨页面使用

由于本插件采用 ES Module 单例 + 系统级蓝牙连接，因此：

• 在 A 页面 connect() 成功后，B 页面 import 进来直接 send() 即可，无需再次 connect。
• 通过 qBluetooth.state 可读取当前是否已连接、当前 deviceId 等信息。
• 事件监听同样跨页面共享，记得在 onUnload 中 off() 掉本页面注册的回调即可。

// B 页面
import qBluetooth from '@/uni_modules/q-bluetooth'

onShow(() => {
  if (qBluetooth.state.connected) {
    qBluetooth.send('B1B2')
  }
})

Vue2 使用方式

Vue2 项目请使用默认导出的 qBluetooth 单例 API。核心蓝牙能力、跨页面连接保持、事件监听都支持 Vue2。

<template>
  <view>
    <view>状态：{{ connected ? '已连接' : '未连接' }}</view>
    <view v-for="d in devices" :key="d.deviceId" @tap="connect(d.deviceId)">
      {{ d.name || '(未命名)' }} - 信号强度 {{ d.signalStrength }}
    </view>
  </view>
</template>

<script>
import qBluetooth from '@/uni_modules/q-bluetooth'

export default {
  data() {
    return {
      connected: false,
      devices: [],
    }
  },
  onLoad() {
    this.onDeviceFound = (devices) => {
      this.devices = devices
    }
    this.onConnectionChange = () => {
      this.connected = qBluetooth.state.connected
    }

    qBluetooth.on('deviceFound', this.onDeviceFound)
    qBluetooth.on('connectionChange', this.onConnectionChange)
  },
  onUnload() {
    qBluetooth.off('deviceFound', this.onDeviceFound)
    qBluetooth.off('connectionChange', this.onConnectionChange)
  },
  methods: {
    async scan() {
      await qBluetooth.init()
      await qBluetooth.startScan()
    },
    async connect(deviceId) {
      await qBluetooth.connect(deviceId)
      this.connected = qBluetooth.state.connected
    },
    async send() {
      await qBluetooth.send('A1B2C3D4')
    },
  },
}
</script>

Vue 3 组合式 API

<script setup>
import { useBluetooth } from '@/uni_modules/q-bluetooth'

const { state, devices, init, startScan, stopScan, connect, send, disconnect } = useBluetooth()
</script>

<template>
  <view>状态：{{ state.connected ? '已连接' : '未连接' }}</view>
  <view v-for="d in devices" :key="d.deviceId" @tap="connect(d.deviceId)">{{ d.name }}</view>
</template>

API

实例属性

方法

事件

devices[]

devices[] 是扫描到的附近蓝牙设备列表，来源于 deviceFound 事件和 getDevices() 方法。插件会按 deviceId 自动去重，并合并同一设备后续扫描到的新信息。

示例：

qBluetooth.on('deviceFound', (devices) => {
  devices.forEach((device) => {
    console.log(device.deviceId)
    console.log(device.name)
    console.log(device.RSSI)
    console.log(device.signalStrength)
  })
})

注意事项

• Android 扫描需要定位权限，App 端请确保 manifest 勾选 ACCESS_FINE_LOCATION。
• 小程序需用户已开启系统蓝牙、定位。
• 默认会自动挑选一组 notify/indicate 与 write 特征；如需指定，向 connect(deviceId, { serviceId, writeCharId, notifyCharId }) 传入即可。

使用案例