更新记录

1.2.3（2025-09-02）

• 优化已知问题;

1.2.2（2025-07-25）

• 添加连接失败信息;

1.2.1（2025-07-25）

• 优化已知问题;

平台兼容性

uni-app(4.75)

uni-app x(4.75)

kaka-KBlue

欢迎使用 kaka-KBlue UTS插件, 此插件使用原生蓝牙(安卓: 经典蓝牙; iOS: BLE).

• 支持蓝牙扫描、连接、断开;
• 支持字节数据、字符串数据写入;
• 蓝牙状态监听、连接状态监听、数据回传监听、数据写入是否完成监听;

导入

import * as KBlue from '@/uni_modules/kaka-KBlue';

蓝牙使用说明

扫描设备

KBlue.startScan({
    callback: (device) => {
        let d = this.deviceList.find((item) => device.deviceId == item.deviceId)
        if (d == undefined) {
            console.log(`发现设备: ${JSON.stringify(device)}`);
            this.deviceList.push(device);
        }
    },
    enableBle: false
});
// callback: 发现设备回调, enableBle: 是否允许扫描出ble设备, 仅针对安卓

停止扫描

KBlue.stopScan();

连接设备

KBlue.connect({
    deviceId: deviceId,
    // serviceUUID、writeUUID、notifyUUID为 可选参数，仅iOS平台有效，用于指定特定的服务和特征
    // serviceUUID: "xxx",
    // writeUUID: "xxx",
    // notifyUUID: "xxx"
}) // 连接设备

断开设备

KBlue.disconnect();

写入数据

• 写入字节数组

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

• 写入字符串

  // 第一个参数为字符串内容，传的字符串需设备支持的指令，这点很重要
  // 第二个参数为字符串编码，不传默认 "UTF_8" 编码，包含中文需传 "GBK"
  KBlue.writeStringCmd("关机", "GBK")

设置分包大小(仅对iOS平台生效，安卓走经典蓝牙)

// 设置的大小需设备支持，不能随意设置，不设置内部会自动匹配
KBlue.setPackageSize(100)

蓝牙事件监听

蓝牙状态监听

KBlue.onBlueStateChange((isOn) => {
    console.log("蓝牙 " + (isOn ? "开启" : "关闭"), isOn);
    this.blueIsOn = isOn;
})

蓝牙连接状态监听

// 蓝牙连接监听
KBlue.onConnectStateChange({
    onSuccess: (device) => {
      console.log(`连接成功: ${JSON.stringify(device)}`);
    },
    onDisconnect: (device) => {
      console.log(`断开连接: ${JSON.stringify(device)}`);
    },
    onFail: (msg) => {
      console.log("连接失败", msg);
    }
});

蓝牙数据回传监听

// 蓝牙数据接收监听
KBlue.onDataReceive((data) => {
    uni.showToast({
      title: `收到蓝牙数据: ${data}`,
      icon: 'none'
    });
    let result = "";
    for (let byte of data) {
      result += String.fromCharCode(byte);
    }
    console.log( `收到蓝牙数据: ${data}`)
    console.log(`收到蓝牙数据转字符串: ${result}`);
});

数据写入是否完成监听

KBlue.onWriteComplete((isComplete) => {
    console.log("写入 " + (isComplete ? "成功" : "失败"), isComplete);
});

蓝牙权限

• 安卓

  <uses-permission android:name="android.permission.BLUETOOTH"/>
  <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"/>

• iOS

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