更新记录

0.00（2026-04-28）

初始版本发布 支持蓝牙配网全流程

平台兼容性

uni-app(5.0)

ble-plugin 插件说明 ble-plugin UniApp 原生蓝牙插件，支持 Android 蓝牙配网、WiFi 列表扫描。 功能特性

• ✅ 蓝牙扫描、连接、断开
• ✅ 蓝牙服务/特征值发现
• ✅ 特征值读写、notify 监听
• ✅ 权限自动检查
• ✅ 兼容 Android 6.0 - 14 安装 方式一：通过 HBuilderX 插件市场
  1. 打开 HBuilderX
  2. 菜单 → 工具 → 插件安装
  3. 搜索 "ble-plugin"
  4. 点击安装 方式二：手动安装
  5. 下载插件包
  6. 解压到项目 nativeplugins/ble-plugin 目录
  7. 在 manifest.json 中配置：

"app-plus": { "plugins": { "ble-plugin": { "version": "1.0.0", "provider": "your-company" } } }

使用示例

const blePlugin = uni.requireNativePlugin('ble-plugin')

// 初始化蓝牙 blePlugin.initBLE((res) => { console.log('initBLE', res) })

// 开始扫描 blePlugin.startScan((device) => { console.log('发现设备', device) })

// 连接设备 blePlugin.createBLEConnection('AA:BB:CC:DD:EE:FF', (res) => { console.log('连接结果', res) })

// 我的平板无强定位（GPS）此方法未实现，采用下方 getCurrentWifiSSID 实现 // 获取 WiFi 列表 blePlugin.getWifiList((res) => { console.log('WiFi 列表', res) })

API 文档 initBLE(callback) 初始化蓝牙模块，检查权限。 startScan(callback) 开始扫描 BLE 设备，callback 会多次调用。 stopScan() 停止扫描。 createBLEConnection(mac, callback) 连接指定 MAC 地址的设备。 closeBLEConnection(mac) 断开指定设备连接。 onBLEConnectionStateChange(callback) 监听蓝牙连接状态变化。 getBLEDeviceServices(mac, callback) 获取设备服务列表。 getBLEDeviceCharacteristics(mac, serviceId, callback) 获取服务的特征值列表。 notifyBLECharacteristicValueChange(mac, serviceId, characteristicId, state, callback) 开启/关闭特征值 notify。 onBLECharacteristicValueChange(callback) 监听特征值变化。 writeBLECharacteristicValue(mac, serviceId, characteristicId, base64Value, callback) getCurrentWifiSSID()

//注：getWifiList 无法使用 可采用方法 获取当前连接的WiFi名称（SSID），返回Promise，适配安卓全版本，需先授权相关权限。

async getCurrentWifiSSID() { return new Promise(async (resolve) => { const sys = uni.getSystemInfoSync(); if (sys.platform !== 'android') { resolve('仅支持安卓APP'); return; }

    // 动态申请权限（安卓必须）
    const authOk = await this.requestAndroidWifiPermission();
    if (!authOk) {
        resolve('请授予权限');
        return;
    }

    try {
        let mainActivity = plus.android.runtimeMainActivity();

        plus.android.importClass("android.net.wifi.WifiManager");
        plus.android.importClass("android.net.wifi.WifiInfo");

        let wifiManager = mainActivity.getSystemService("wifi");

        if (!wifiManager.isWifiEnabled()) {
            resolve('请打开手机WiFi');
            return;
        }

        let wifiInfo = wifiManager.getConnectionInfo();
        let ssid = wifiInfo.getSSID();

        if (!ssid || ssid === "<unknown ssid>" || ssid === "0x") {
            resolve('未获取到WiFi名称');
            return;
        }

        ssid = ssid.replace(/"/g, "");
        resolve({
            code: 200,
            ssid
        });

    } catch (e) {
        console.error("WiFi错误详情：", e);
        resolve("获取失败");
    }
});

},

注意事项

• Android 6.0+ 需要动态申请定位权限
• Android 12+ 需要 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 权限
• WiFi 扫描需要定位权限
• 特征值写入/读取需要 Base64 编码转换 getWifiList(callback) 获取周边 WiFi 列表（自动过滤 5G）。 注意事项
• Android 6.0+ 需要动态申请定位权限
• Android 12+ 需要 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 权限
• WiFi 扫描需要定位权限
• 特征值写入/读取需要 Base64 编码转换