uni-app开发中如何用plus.android.importClass搞定蓝牙设备连接（附完整代码示例）

原创

于 2026-03-02 02:48:17 发布 · 560 阅读

在uni-app中驾驭Android原生蓝牙：从plus.android.importClass到稳定连接实战

如果你是一位uni-app开发者，正面临着一个看似简单却充满“坑”的任务：在你的跨平台应用中集成蓝牙功能，特别是需要与特定的硬件设备（比如打印机、扫描枪、传感器）进行稳定通信，那么这篇文章就是为你准备的。你可能已经尝试过一些通用的蓝牙插件，却发现它们在面对特定厂商协议或复杂交互逻辑时力不从心。这时，直接调用Android原生蓝牙API就成了一个必须掌握的“硬核”技能。本文将带你绕过概念迷宫，直击核心，通过plus.android.importClass这座桥梁，深入Android蓝牙开发的腹地，构建一套健壮、可复用的设备连接与通信方案。我们将从环境认知开始，一步步走到数据传输，并附上经过实战检验的完整代码。

1. 理解桥梁：plus.android.importClass的本质与边界

在uni-app的语境下，我们写的代码是JavaScript（或Vue语法），它运行在一个WebView环境中。这个环境本身无法直接操作手机的蓝牙硬件。而Android系统提供了强大且完整的蓝牙开发接口（Java API），它们存在于另一个“世界”。plus.android.importClass的作用，就是在这两个世界之间打开一扇门，允许JavaScript代码“看见”并“调用”Java世界的类和方法。

这不仅仅是简单的函数映射。当你调用plus.android.importClass(“android.bluetooth.BluetoothAdapter”)时，uni-app的底层引擎（HTML5+ Runtime）会通过JNI（Java Native Interface）机制，在JavaScript运行时中创建一个代理对象。这个代理对象镜像了Java类BluetoothAdapter的公共方法和属性。你后续通过这个代理对象进行的操作，都会被引擎翻译成对应的Java调用，并最终由Android系统执行。

注意：这扇“门”只在特定的墙上有效。plus.android系列API是DCloud HTML5+引擎为Android平台提供的原生扩展，它仅在打包后的Android App或HBuilderX的Android自定义调试基座中生效。在浏览器、iOS小程序或App中，这些代码将无法执行。

理解这一点至关重要，它决定了我们代码的编写方式：必须进行平台判断。我们不能假设代码永远运行在Android环境。一个健壮的项目结构应该像这样：

// utils/bluetooth-connector.js
export function initBluetoothModule() {
    // 1. 环境检测
    if (plus.os.name !== 'Android') {
        console.warn('蓝牙原生模块仅支持Android平台。iOS请使用其他方案。');
        return null; // 或返回一个模拟对象/错误码
    }

    // 2. 检查运行环境（可选但推荐，用于开发阶段快速排错）
    if (typeof plus.android === 'undefined') {
        console.error('当前运行环境不支持 plus.android API，请确保使用Android基座或已打包的APK。');
        return null;
    }

    // 3. 只有通过上述检查，才进行原生类的导入
    try {
        const BluetoothAdapter = plus.android.importClass('android.bluetooth.BluetoothAdapter');
        // ... 后续初始化逻辑
        return { BluetoothAdapter /*, 其他导出对象 */ };
    } catch (error) {
        console.error('导入Android蓝牙类失败:', error);
        return null;
    }
}

这种“防御性编程”能避免应用在非目标平台崩溃，也为后续兼容其他平台（如使用plus.ios或uni-app插件）留出了清晰的接口。

2. 搭建舞台：权限、适配器与设备发现

在开始搜索设备之前，我们必须确保应用拥有合法的“通行证”，并且蓝牙硬件本身是可用的。这个阶段任何疏忽都会导致后续所有操作失败。

2.1 权限申请：不仅仅是配置manifest

是的，你需要在manifest.json中正确声明蓝牙权限：

{
    "app-plus": {
        "distribute": {
            "android": {
                "permissions": [
                    "android.permission.BLUETOOTH",
                    "android.permission.BLUETOOTH_ADMIN",
                    "android.permission.ACCESS_FINE_LOCATION" // Android 6.0+ 搜索蓝牙设备需要
                ]
            }
        }
    }
}

但声明不等于拥有。在Android 6.0（API level 23）及以上版本，ACCESS_FINE_LOCATION属于危险权限，需要运行时动态申请。许多开发者在这里栽了跟头，设备搜索列表始终为空，问题往往就出在动态权限上。

下面是一个结合uni-app API和Android原生API进行权限检查和申请的函数：

async function checkAndRequestBluetoothPermissions() {
    return new Promise((resolve, reject) => {
        // 首先检查是否为Android环境
        if (plus.os.name !== 'Android') {
            resolve(false);
            return;
        }

        const Context = plus.android.importClass('android.content.Context');
        const Activity = plus.android.runtimeMainActivity();
        const PackageManager = plus.android.importClass('android.content.pm.PackageManager');

        const permissionsToCheck = [
            'android.permission.BLUETOOTH',
            'android.permission.BLUETOOTH_ADMIN',
            'android.permission.ACCESS_FINE_LOCATION'
        ];

        let allGranted = true;
        for (const perm of permissionsToCheck) {
            // 检查单个权限
            if (Activity.checkSelfPermission(perm) !== PackageManager.PERMISSION_GRANTED) {
                allGranted = false;
                break;
            }
        }

        if (allGranted) {
            resolve(true);
        } else {
            // 动态申请缺失的权限
            plus.android.requestPermissions(permissionsToCheck, (result) => {
                // result 是一个对象，键为权限名，值为授权状态码
                const granted = Object.values(result).every(
                    code => code === PackageManager.PERMISSION_GRANTED
                );
                resolve(granted);
            }, (error) => {
                console.error('申请权限出错:', error);
                reject(error);
            });
        }
    });
}