Uniapp-Android原生插件开发

开发教程

https://nativesupport.dcloud.net.cn/NativePlugin/README

uni 原生插件类型

Module 模式「类似于前端里的 js sdk」：能力扩展，无嵌入窗体的 UI 控件。大部分插件都是属于此类，比如调用计步器 API。代码写法为通过 js 进行 require，然后调用该插件对象的方法。如涉及一些弹出框、全屏 ui，也仍然属于 Module 模式
Component 模式「类似于前端里的 vue 组件」：在窗体中内嵌显示某个原生 ui 组件。比如窗体局部内嵌某个地图厂商的 map 组件，上下混排其他前端内容，就需要把这个原生地图 sdk 封装为 Component 模式。代码写法与 vue 组件相同，在 template 里写组件标签

uni-app 在 App 端支持双渲染引擎，支持 vue 和 nvue 两种页面，vue 页面基于 webview 排版引擎渲染，nvue 页面基于优化版的 weex 原生排版引擎渲染，weex 的插件也可以拿到 uni-app 生态中使用。

vue 页面中仅支持使用 Module 类型的原生插件，不支持调用同步方法返回数据
nvue 页面中支持使用 Module 和 Component 两种类型的原生插件。也就是如需实现嵌入页面的 ui 组件，前提是该页面需要使用 nvue 编写。

注意

调试

页面逻辑调试在 HbuilderX 中完成，可以查看 App 页面，弹出信息，查看HbuilderX 输出的日志信息
调试插件中代码逻辑时，在 Android studio 中完成。与 Android 原生开发调试一样，设置断点，查看变量，输出日志等
可以通过 Android Studio 制作自定义基座。在 HBuilderX 中运行时选择自定义基座，然后调试页面和插件交互功能，但 HBuilderX 控制台不再输出信息，只能通过弹窗形式查看过程信息

步骤

在现有 Android 项目中创建 library 的 module，例如 uniplugin_module

配置 module 的 build.gradle 信息

//导入aar需要的配置
repositories {
    flatDir {
        dirs 'libs'
    }
}
dependencies {
    //必须添加的依赖
    compileOnly 'com.android.support:recyclerview-v7:28.0.0'
    compileOnly 'com.android.support:support-v4:28.0.0'
    compileOnly 'com.android.support:appcompat-v7:28.0.0'
    compileOnly 'com.alibaba:fastjson:1.1.46.android'

    compileOnly fileTree(include: ['uniapp-v8-release.aar'], dir: '../app/libs')
}

创建插件类，必须继承 UniModule 类
1
public class TestModule extends UniModule
扩展方法必须加上 @UniJSMethod (uiThread = false or true) 注解。UniApp 会根据注解来判断当前方法是否要运行在 UI 线程，和当前方法是否是扩展方法
UniApp 是根据反射来进行调用 Module 扩展方法，所以 Module 中的扩展方法必须是 public 类型

方法参考可以是 int, double, float, String, Map, List ,com.alibaba.fastjson.JSONObject 类型

示例：

//run ui thread
@UniJSMethod(uiThread = true)
public void testAsyncFunc(JSONObject options, UniJSCallback callback) {
    Log.e(TAG, "testAsyncFunc--"+options);
    if(callback != null) {
        JSONObject data = new JSONObject();
        data.put("code", "success");
        callback.invoke(data);
    }
}

//run JS thread
@UniJSMethod (uiThread = false)
public JSONObject testSyncFunc(){
    JSONObject data = new JSONObject();
    data.put("code", "success");
    return data;
}

globalEvent 事件

用于页面监听持久性事件，例如定位信息，陀螺仪等的变化。

示例：

页面监听 event 事件

var globalEvent = uni.requireNativePlugin('globalEvent');
globalEvent.addEventListener('myEvent', function(e) {
  console.log('myEvent'+JSON.stringify(e));
});Copy to clipboardErrorCopied

插件原生代码发出 myEvent 事件

1
2
3

Map<String,Object> params=new HashMap<>();
params.put("key","value");
mUniSDKInstance.fireGlobalEventCallback("myEvent", params);Copy to clipboardErrorCopied

注意 globalEvent 事件只能通过页面的 UniSDKInstance 实例给当前页面发送 globalEvent 事件。其他页面无法接受。

本地插件注册
- 在 UniPlugin-Hello-AS 工程下 “app” Module 根目录 assets/dcloud_uniplugins.json 文件。在 moudles 节点下添加你要注册的 Module 或 Component
集成 uni-app 项目测试插件
1. 创建 uni-app 工程或在已有的 uni-app 工程编写相关的.nvue 和.vue 文件。使用 uni-app 插件中的 module 或 component
2. 选择发行 —> 原生 APP - 本地打包 —> 生成本地打包 App 资源等待资源生成！
3. 把 APP 资源文件放入到 UniPlugin-Hello-AS 工程下 app Module 根目录 assets/apps/ 测试工程 appid/www 对应目录下，再修改 assets/data/dcloud_control.xml! 修改其中 appid=“测试工程 appid”!, 测试工程 UniPlugin-Hello-AS 已有相关配置可参考
4. appid 注意一定要统一否则会导致应用无法正常运行
5. 配置 “app”Module 下的 build.gradle. 在 dependencies 节点添加插件 project 引用（以 uniplugin_richalert 为例）
1
2
// 添加uni-app插件
implementation project(':uniplugin_richalert')
1. 运行测试。测试运行时一切要以真机运行为主。

插件 module 打包成 aar

选择 Gradle—> 插件 module—>Tasks—>build—>assembleRelease 编译 module 的 aar 文件

注意：新版本 Android studio 将 assembleRelease 放入 other 中了

开发教程

uni 原生插件类型

注意

调试

步骤

globalEvent 事件

集成 uni-app 项目测试插件

插件 module 打包成 aar