【Uniapp】Uniapp Android原生插件开发指北

前言

在uniapp开发中当HBuilderX中提供的能力无法满足App功能需求，需要通过使用Andorid/iOS原生开发实现时，或者是第三方公司提供的是Android的库，这时候可使用App离线SDK开发原生插件来扩展原生能力。

插件类型有两种，Module模式和Component模式

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

本文主要讨论的是Module模式的开发。

开发环境准备

开发环境：JAVA环境 jdk1.8 和Android X
Android studio，最新的Hbuilderx，最新的离线uniSdk

插件必须在uni-sdk的基础上进行开发，可以快速的下载离线uni-sdk，导入UniPlugin-Hello-AS示例工程，也可以自己新建一个原生android项目，拷贝不要的包和资源进行开发。

开发原生插件

1、导入uni插件原生项目（离线uni-sdk中解压），并且成功编译。打开后目录如下：
在这里插入图片描述

Module插件的开发，是一个Module构建成一个插件aar，因为需要新建一个插件实现新的功能。

2、创建Module

在现有Android项目中创建library的Module。例如uniplugin_readcard，配置刚创建的Module的build.gradle信息。

//导入aar需要的配置
repositories {flatDir {dirs 'libs'}
}
dependencies {//必须添加的依赖compileOnly 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0',compileOnly 'androidx.core:core:1.1.0'compileOnly 'androidx.fragment:fragment:1.1.0'compileOnly 'androidx.appcompat:appcompat:1.1.0'compileOnly 'androidx.recyclerview:recyclerview:1.1.0'compileOnly 'com.alibaba:fastjson:1.2.83'compileOnly fileTree(include: ['uniapp-v8-release.aar'], dir: '../app/libs')
}

此处的lib aar都在APP模块下有，不需要额外的导入。uniapp-v8-release.aar是扩展module主要依赖库，必须导入此依赖库！打包成插件时候不需要打包进入这些依赖库，只需要打包进去你额外添加的依赖库。
在这里插入图片描述

如图，新的module下，新建两个文件，ReadModule和ReadCard_AppProxy，
如果项目需要导入so包、aar或者jar包，导入放到libs下，

在这里插入图片描述

ReadModule 是暴露于外的核心的类，需要继承于UniModule ，打包插件时候需要配置到package.json的class位置。

public class ReadModule extends UniModule  {@UniJSMethod (uiThread = true)public void showToastAAA(JSONObject options, UniJSCallback jsCallback) {Toast.makeText(mUniSDKInstance.getContext(), "Hello", Toast.LENGTH_SHORT).show();JSONObject result = new JSONObject();try {result.put("cardno", "hello");jsCallback.invoke(result);} catch (JSONException e) {throw new RuntimeException(e);}}@UniJSMethod (uiThread = true)public void showTest(UniJSCallback jsCallback) {Toast.makeText(mUniSDKInstance.getContext(), "Hello", Toast.LENGTH_SHORT).show();JSONObject result = new JSONObject();try {result.put("cardno", "hello");jsCallback.invoke(result);} catch (JSONException e) {throw new RuntimeException(e);}}@SuppressLint("MissingPermission")@UniJSMethod (uiThread = true)public void piccrequest(JSONObject options, UniJSCallback jsCallback) {TelephonyManager telephonyManager = (TelephonyManager)mUniSDKInstance.getContext().getSystemService(Context.TELEPHONY_SERVICE);if (telephonyManager != null) {Map<String,String> result = new HashMap<>();result.put("imei",  telephonyManager.getDeviceId().toString());jsCallback.invoke(result);}}

注意

1）对外暴露的方法需要添加 @UniJSMethod (uiThread = true)，并且设置为public 。
2）JSONObject options可以接收uniapp传过来的数据，也可以为空。
3）jscallback回调的时候，可以用JSONObject 存放数据，回调json数据，但是某些时候回调不到，可以切换成Map。

{"name": "ReadCardModule","id": "ReadCardModule", "version": "1.0.0","description": "读卡","_dp_type":"nativeplugin","_dp_nativeplugin":{"android": {"integrateType":"aar","plugins": [{"type": "module","name": "ReadCardModule", "class": "uni.dcloud.io.uniplugin_read.ReadModule"}]}}
}

注意
1）package.json的class的路径是Module 中ReadModule 的路径
2）name、id、name可以起同一个名字，避免出现错误
3）plugins的name名字用作于uniapp中的引用。

var testModule = uni.requireNativePlugin("ReadCardModule")

3、如果项目中需要进行第三方库初始化，可以新建一个ReadCard_AppProxy 实现UniAppHookProxy并且配置到，即可在oncreate中进行初始化。

public class ReadCard_AppProxy implements UniAppHookProxy {@Overridepublic void onCreate(Application application) {//可写初始化触发逻辑}@Overridepublic void onSubProcessCreate(Application application) {//子进程初始化回调}
}

在UniPlugin-Hello-AS工程下 “app” Module根目录assets/dcloud_uniplugins.json文件，在hooksClass节点添加你创建实现UniAppHookProxy接口的实体类完整名称填入其中即可 (有些需要初始化操作的需求可以在此处添加逻辑，无特殊操作仅使用第一种方式注册即可无需集成UniAppHookProxy接口)

开发完成后，在gradle中进行assembleRelease，即可打包成插件的aar，

在这里插入图片描述

打包给uniapp端或者上传插件市场的文件如下，package.json就是上文所描述的配置文件，Android文件夹中，项目的so包和jar包放到libs下，项目所依赖的aar和打包的插件aar放到Android目录下，资源文件放到res或者assets下。

千万不要放错位置！！
千万不要放错位置！！
千万不要放错位置！！

在这里插入图片描述

如此，一个基础的插件开发就算完成，理论上可以交给uniapp端进行使用。copy上面的文件夹放到nativeplugins下面，mainifest.json中原生插件选择一下，然后制作自定义基座打包，就可以进行使用了。

var myPlugin= uni.requireNativePlugin("ReadCardModule")myPlugin.piccrequest({  }, (res) => {  // 处理原生方法返回的结果  console.log('读卡结果:', res);  }, (err) => {  // 处理调用插件时发生的错误  console.error('调用插件失败:', err);  });

但是uniapp端使用插件需要自定义基座和云打包时间特别长，Android模块需要保证自己的插件没有问题，是通顺的，再给uniapp使用比较好。因此，再开发完成后，在Android studio中对uniapp进行离线打包和测试是比较重要的。

uniapp插件调试

1、离线打包

对于不熟悉Android的人来说，离线打包有时候难度很大。

1）hbuilder中打包资源包。

条件准备

申请离线appkey
申请离线appkey包括两部分：生成签名证书和申请离线appkey

生成签名证书
dcloud官方文档：https://ask.dcloud.net.cn/article/35777

签名证书用jdk自带的工具keytool生成：

keytool -genkey -alias androidPluginKey -keyalg RSA -keysize 2048 -validity 36500 -keystore androidPluginKey.keystore

androidPluginKey是证书别名，可修改为自己想设置的字符，建议使用英文字母和数字
在这里插入图片描述

申请离线appkey

在这里插入图片描述

打包资源

在这里插入图片描述

把资源配置到Android studio项目中

把资源包复制到项目中
在这里插入图片描述

配置证书

确保appid+签名证书+应用包名都一致
在这里插入图片描述

在dcloud_control.xml填写uniappId

在这里插入图片描述

在主app中添加上插件的libary

implementation project(':uniplugin_readcard')

注册插件
在androidStudio的assets里面新建dcloud_uniplugins.json，并注册插件信息

在这里插入图片描述

如此就完成了uniapp离线打包的配置，即可在此基础上进行调试，

每次调试时在uniapp中进行修改->打包离线资源包->替换掉Android studio中的资源包。

uniapp插件使用

在hbuilder的根目录下新建nativeplugins文件夹，把把上面的文件夹（包含lib aar等资源的）放到内部
f 在这里插入图片描述

打开manifest.json进行插件的选择
在这里插入图片描述

使用插件

在项目中所需要用到的地方，引用插件，调用即可，

var myPlugin= uni.requireNativePlugin("ReadCardModule")myPlugin.piccrequest({  }, (res) => {  // 处理原生方法返回的结果  console.log('读卡结果:', res);  }, (err) => {  // 处理调用插件时发生的错误  console.error('调用插件失败:', err);  });

制作自定义基座

代码完成后，可以进行自定义基座打包，即可完成开发。
在这里插入图片描述