Uniapp插件开发实战：从零构建Android原生弹窗插件
第一次接触Uniapp原生插件开发时，我盯着官方文档里"需要Android/iOS原生开发经验"的提示犹豫了整整两周。直到发现官方提供的UniPlugin-Hello-AS工程模板，才意识到原来门槛可以这么低——只要会JavaScript和基础Java语法，就能开发简单的原生插件。本文将带你用最简化的方式，完成一个显示系统弹窗的Android原生插件开发全流程。
1. 环境准备与工程搭建
开发Uniapp原生插件需要配置以下环境（以Windows系统为例）：
- HBuilderX 3.4.0+：确保安装了App开发套件
- Android Studio 2021.2.1+：推荐使用稳定版
- Java JDK 11：配置好JAVA_HOME环境变量
- Node.js 14+：用于依赖管理
提示：Android Studio安装时务必勾选"Android SDK"和"Android SDK Command-line Tools"
下载官方示例工程：
git clone https://github.com/dcloudio/UniPlugin-Hello-AS.git用Android Studio打开后，关键目录结构如下：
UniPlugin-Hello-AS ├── app # 主模块 ├── plugin_hello # 示例插件模块 ├── README.md └── settings.gradle2. 创建自定义插件模块
在Android Studio中右键项目 → New → Module → Android Library，命名为toast_plugin。然后修改build.gradle：
apply plugin: 'com.android.library' android { compileSdkVersion 31 defaultConfig { minSdkVersion 21 targetSdkVersion 31 } } dependencies { implementation 'androidx.appcompat:appcompat:1.4.1' implementation project(':uniplugin_component') implementation project(':uniplugin_module') implementation project(':uniplugin_richalert') }创建核心类ToastPlugin.java：
package com.example.toastplugin; import android.content.Context; import android.widget.Toast; import io.dcloud.feature.uniapp.annotation.UniJSMethod; import io.dcloud.feature.uniapp.bridge.UniJSCallback; import io.dcloud.feature.uniapp.common.UniModule; public class ToastPlugin extends UniModule { @UniJSMethod(uiThread = true) public void showToast(String message) { if(mUniSDKInstance != null) { Context context = mUniSDKInstance.getContext(); Toast.makeText(context, message, Toast.LENGTH_SHORT).show(); } } }3. 插件注册与配置
在toast_plugin模块的src/main目录下新建assets文件夹，创建dcloud_uniplugins.json：
{ "nativePlugins": [ { "hooksClass": "", "plugins": [ { "type": "module", "name": "ToastPlugin", "class": "com.example.toastplugin.ToastPlugin" } ] } ] }修改主模块的build.gradle，添加对新插件的依赖：
dependencies { implementation project(':toast_plugin') }4. 生成自定义基座
在Android Studio中：
- 点击Build → Generate Signed Bundle / APK
- 选择APK → 创建或选择现有签名文件
- Build Variants选择release
- 等待构建完成，生成的APK在
app/release/目录下
将生成的APK文件重命名为android_debug.apk，复制到HBuilderX项目的unpackage/debug/目录（需先创建该目录）
5. Uniapp调用插件
在HBuilderX项目中创建测试页面：
<template> <view class="content"> <button @click="showToast">点击显示原生弹窗</button> </view> </template> <script> export default { methods: { showToast() { const toastModule = uni.requireNativePlugin('ToastPlugin') toastModule.showToast('Hello from Native!') } } } </script>配置manifest.json启用自定义基座：
"app-plus": { "usingComponents": true, "plugins": { "ToastPlugin": { "version": "1.0.0", "provider": "com.example.toastplugin" } } }6. 调试与问题排查
常见问题及解决方案：
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 找不到插件 | 插件未正确注册 | 检查dcloud_uniplugins.json配置 |
| 方法调用无效 | 方法未添加@UniJSMethod注解 | 确保所有暴露方法都有正确注解 |
| 基座运行无效果 | 未使用自定义基座 | 确认HBuilderX运行的是自定义基座 |
调试技巧：
- 在Android Studio的Logcat中过滤"uniPlugin"查看插件日志
- 使用
adb logcat命令实时查看设备日志 - 修改插件代码后需要重新打包APK并替换基座文件
7. 插件功能扩展
基础弹窗功能运行成功后，可以尝试扩展更多实用功能：
设备信息获取示例：
@UniJSMethod(uiThread = true) public void getDeviceInfo(UniJSCallback callback) { if(mUniSDKInstance == null || callback == null) return; Activity activity = mUniSDKInstance.getContext(); WifiManager wifi = (WifiManager)activity.getSystemService(Context.WIFI_SERVICE); WifiInfo info = wifi.getConnectionInfo(); JSONObject data = new JSONObject(); try { data.put("model", Build.MODEL); data.put("sdkVersion", Build.VERSION.SDK_INT); data.put("macAddress", info.getMacAddress()); } catch (JSONException e) { e.printStackTrace(); } callback.invoke(data); }JS端调用方式：
toastModule.getDeviceInfo(res => { console.log('设备信息:', res) })8. 性能优化建议
- 减少跨语言调用：批量传输数据优于频繁调用
- 异步处理耗时操作：避免阻塞UI线程
- 合理使用缓存：对不变的数据进行缓存
- 内存管理：及时释放不再使用的资源
优化后的调用示例：
@UniJSMethod(uiThread = false) public void complexOperation(JSONObject params, UniJSCallback callback) { // 在子线程执行耗时操作 String result = doHeavyWork(params); // 返回结果到JS线程 mUniSDKInstance.runOnUiThread(new Runnable() { @Override public void run() { if(callback != null) { callback.invoke(result); } } }); }在实际项目中，我发现插件初始化的性能开销较大，推荐将多个相关功能整合到一个插件模块中，而不是创建多个小型插件。
