更新记录

1.0.0（2025-09-13）

• 安卓经典蓝牙;

平台兼容性

uni-app(4.76)

uni-app x(4.76)

xl-classicblue 开发文档

购买说明

• 购买插件前请先试用，试用满意再购买。在试用中如遇到问题, 欢迎进入交流群, 将全力协助你使用本插件。

概述

本SDK提供了一套完整的蓝牙低功耗(blueTool.)设备交互接口，采用模块化设计，将功能接口与回调监听分离，便于开发者灵活使用。

• 支持蓝牙扫描、连接、断开;

• 支持字节数据、字符串数据写入;

• 蓝牙状态监听、连接状态监听、数据回传监听、数据写入是否完成监听;

• 支持GBK编码;

导入

import * as blueTool from '@/uni_modules/xl-classicblue'

功能接口说明

扫描设备

// callback: 发现设备回调
blueTool.startScan((device) => {
  console.log(`发现设备: ${JSON.stringify(device)}`);
});

停止扫描

blueTool.stopScan();

连接设备

// 参数1: 设备id
// 参数2(可选):指定服务与特征，未指定内部会自动匹配
blueTool..connect(deviceId,)

断开设备

blueTool.disconnect()

写入数据

• 写入字节数组

  // 参数为字节数组，需设备支持的指令，这点很重要
  blueTool.writeBytes([0x10, 0xff, 0x30])

• 写入字符串

  // 参数1: 字符串内容，传的字符串需设备支持的指令，这点很重要
  // 参数2(可选): 字符串编码, 默认 "UTF_8" 编码, 传 "GBK" 使用GBK编码
  blueTool.writeString('ABC')
  blueTool.writeString('ABC', 'GBK')

蓝牙事件监听

蓝牙状态监听

blueTool..onBluetoothStatusChanged((isOn) => {
  uni.showToast({
    title: isOn ? "蓝牙已开启" : "蓝牙已关闭",
    icon: 'none'
  });
});

蓝牙连接状态监听

blueTool.onConnectionStateChange((payload) => {
  uni.showToast({
    title: payload.state,
    icon: 'none'
  })
  switch (payload.state) {
    case 'connectFail':
                // 连接失败
      break;
    case 'disconnected':
                // 断开连接
      break;
    case 'connected':
      // 断开成功
      break;
  }
});

蓝牙数据回传监听

blueTool.onDataReceived((data) => {
  let result = String.fromCharCode(...data);
  console.log(`收到蓝牙数据: ${data}`)
  console.log(`收到蓝牙数据转字符串: ${result}`);
});

数据写入是否完成监听

blueTool.onWriteComplete((isComplete) => {
  console.log(isComplete ? "写入完成" : "写入失败");
})

蓝牙权限

• 安卓

  <uses-permission android:name="android.permission.BLUETOOTH"/>
  <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
  <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
  <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

• iOS

  <key>NSBluetoothAlwaysUsageDescription</key>
  <string>开启蓝牙</string>
  <key>NSBluetoothPeripheralUsageDescription</key>
  <string>蓝牙</string>
  <key>UIBackgroundModes</key>
  <array>
    <string>bluetooth-central</string>
  </array>

类型定义

设备信息

interface BlueDevice {
  name: string       // 设备名称
  deviceId: string   // 设备唯一标识
}

连接状态

type ConnectionState = {
  status: 'connected' | 'disconnected' | 'failed'
  device: BlueDevice,
    msg? : string
}