UniApp实战：5步搞定Android原生插件开发（附完整代码示例）
UniApp实战：5步搞定Android原生插件开发（附完整代码示例）
在跨平台开发领域，UniApp凭借"一次开发，多端运行"的特性赢得了大量开发者的青睐。但当遇到需要调用原生设备功能或性能敏感场景时，原生插件开发就成为必须掌握的技能。本文将带你从零开始，用最简洁的路径完成Android原生插件开发全流程。
1. 环境准备与工程初始化
开发Android原生插件需要配置特定的工具链。首先确保本地已安装：
- Android Studio（最新稳定版）
- Java JDK 11+（推荐使用OpenJDK）
- Node.js（LTS版本）
- HBuilderX（UniApp官方IDE）
关键步骤是获取UniApp官方提供的Android离线SDK。这个SDK包含了开发原生插件所需的核心库文件。下载后解压到本地目录，你会看到如下关键文件：
UniPlugin-Hello-AS/ ├── app/ ├── UniPlugin-Hello-AS.iml ├── build.gradle └── settings.gradle提示：建议将工程目录放在没有中文和空格的路径下，避免Gradle构建时出现意外问题。
2. 创建插件模块
在Android Studio中打开下载的UniPlugin-Hello-AS工程后，我们需要新建一个Library模块：
- 右键项目 → New → Module
- 选择"Android Library"
- 命名模块（如
my_uniapp_plugin） - 确保Minimum SDK ≥ 21
接下来配置模块的build.gradle文件，添加必要的依赖项：
dependencies { compileOnly fileTree(dir: 'libs', include: ['*.jar']) compileOnly fileTree(dir: '../app/libs', include: ['uniapp-v8-release.aar']) compileOnly 'androidx.appcompat:appcompat:1.4.1' implementation 'com.alibaba:fastjson:1.2.83' }这些依赖项确保了插件可以正常与UniApp运行时交互。
3. 编写插件核心逻辑
所有UniApp原生插件都需要继承UniModule基类。下面是一个获取设备信息的完整示例：
package com.example.my_uniapp_plugin; import io.dcloud.feature.uniapp.annotation.UniJSMethod; import io.dcloud.feature.uniapp.common.UniModule; import android.content.Context; import android.os.Build; public class DeviceInfoPlugin extends UniModule { @UniJSMethod(uiThread = true) public String getDeviceInfo() { return "Manufacturer: " + Build.MANUFACTURER + "\n" + "Model: " + Build.MODEL + "\n" + "SDK Version: " + Build.VERSION.SDK_INT; } @UniJSMethod(uiThread = false) public String getAppVersion() { try { Context context = mUniSDKInstance.getContext(); return context.getPackageManager() .getPackageInfo(context.getPackageName(), 0) .versionName; } catch (Exception e) { return "unknown"; } } }关键点说明：
@UniJSMethod注解标记了可供JS调用的方法uiThread参数决定方法是否在主线程执行- 通过
mUniSDKInstance可以获取Android上下文
4. 构建与打包插件
完成代码编写后，需要生成可发布的AAR文件。在Android Studio的Terminal中执行：
./gradlew :my_uniapp_plugin:assembleRelease生成的AAR文件位于：
my_uniapp_plugin/build/outputs/aar/my_uniapp_plugin-release.aar同时需要创建插件的配置文件package.json：
{ "name": "DeviceInfoPlugin", "id": "DeviceInfoPlugin", "version": "1.0.0", "description": "获取设备信息的原生插件", "_dp_type": "nativeplugin", "_dp_nativeplugin": { "android": { "plugins": [ { "type": "module", "name": "DeviceInfoPlugin", "class": "com.example.my_uniapp_plugin.DeviceInfoPlugin" } ], "integrateType": "aar", "minSdkVersion": 21 } } }5. UniApp集成与调试
将打包好的插件集成到UniApp项目中：
- 在项目根目录创建
nativeplugins文件夹 - 新建插件目录
DeviceInfoPlugin - 创建
android子目录，放入AAR文件 - 将
package.json放在插件根目录
目录结构如下：
nativeplugins/ └── DeviceInfoPlugin/ ├── android/ │ └── my_uniapp_plugin-release.aar └── package.json然后在manifest.json中启用插件：
"app-plus": { "plugins": { "DeviceInfoPlugin": { "version": "1.0.0", "provider": "DeviceInfoPlugin" } } }最后在页面中使用插件：
const devicePlugin = uni.requireNativePlugin('DeviceInfoPlugin'); export default { methods: { showDeviceInfo() { const info = devicePlugin.getDeviceInfo(); uni.showModal({ title: '设备信息', content: info, showCancel: false }); } } }重要：每次添加或更新插件后，必须重新打包自定义调试基座，否则修改不会生效。
6. 高级技巧与性能优化
在实际项目中，我们还需要考虑以下进阶场景：
线程管理最佳实践
- UI相关操作强制在主线程执行
- 耗时操作应在子线程完成
- 使用
@UniJSMethod(uiThread = true/false)明确指定
跨平台兼容处理
@UniJSMethod public Object getPlatformInfo() { JSONObject result = new JSONObject(); try { result.put("platform", "Android"); result.put("version", Build.VERSION.RELEASE); } catch (JSONException e) { e.printStackTrace(); } return result; }错误处理机制
@UniJSMethod public void performAction(String params) { try { // 业务逻辑 } catch (Exception e) { mUniSDKInstance.onException(e); } }性能敏感场景优化
- 避免频繁的Java-JS互调
- 批量传输数据时使用JSON格式
- 考虑使用WebWorker处理复杂计算
通过这六个步骤，你已经掌握了UniApp Android原生插件开发的核心流程。在实际项目中，建议从简单功能开始，逐步扩展到复杂场景。