uniapp安卓原生插件开发教程

一、简介

本文档介绍如何在uni-app中基于weexsdk 开发Android原生插件。

二、开发者须知

在您阅读此文档时，我们假定您已经具备了相应Android应用开发经验，使用Android Studio开发过Android原生。学习过 weex 知识并能够理解相关概念。您也应该对HTML,JavaScript,CSS等有一定的了解, 并且熟悉在JavaScript和JAVA环境下的JSON格式数据操作等。

三、前期准备

安装JDK version>=1.7 并配置了环境变量

安装Android SDK 并配置环境变量。

安装Android Studio 尽量使用最新版本！下载地址：Android Studio官网 OR Android Studio中文社区

5+SDK下载：最新android平台SDK下载

学习weex 0.26.0版本框架API。weex扩展API for android

四、插件开发

导入UniPlugin-Hello-AS工程
- UniPlugin-Hello-AS工程请在5+SDK中查找
- 点击Android Studio菜单选项File--->New--->Import Project。
- 导入选择UniPlugin-Hello-AS工程，点击OK! 等待工程导入完毕。
- 如果出现Android SDK路径不对问题，请在Android Studio中鼠标右键UniPlugin-Hello-AS选择Open Module Settings, 在SDK Location 中设置相关环境路径
- 注意！工程gradle配置的gradle-4.6-all版本！使用的是新版本的依赖方式，如果您使用的是老版本的gradle。可根据以下链接进行修改依赖方式。
  gradle新依赖方式与旧依赖方式的不同

创建uni-app插件Module
- 点击Android Studio 菜单项 File--->New--->New Module。
- 选择Android Library, 点击Next.填写与插件相关信息点击finish。
- 编辑module的build.gradle文件。添加依赖库
  Android Studio默认会在dependencies节点下添加一些基本依赖库，如下图红框内的引用注释掉或改为compileOnly依赖方式
  此处需要注意libs文件夹下的jar文件已改为compileOnly方式引用了。当你离线工程调试时需要把插件中用到的jar文件在app工程的build.gradle中配置相应的jar文件implementation引入。一定要注意！！！否则导致应用闪退等问题。至于插件中用到的jar文件在打插件包时文件到底放在什么位置请留意插件打包文档。
- 加入以下引用（出现底色标红表示当前引用版本与compileSdkVersion版本不同，忽略即可）
```
compileOnly "com.android.support:recyclerview-v7:26.1.0"  
compileOnly "com.android.support:support-v4:26.1.0"  compileOnly "com.android.support:appcompat-v7:26.1.0"  
```
  dependencies节点添加依赖库时需使用compileOnly依赖方式！防止打包时与其他插件资源库冲突导致打包失败！！
- 导入uniapp-release.aar
```
    repositories {  
        flatDir {  
            dirs 'libs'  
        }      }  
```
- dependencies节点里添加 :
  (注意：此添dir需根据具体工程目录配置，当前写法仅适用于UniPlugin-Hello-AS工程)
```
compileOnly fileTree(dir: '../app/libs', include: ['uniapp-release.aar'])  
```
  完成以上操作表示当前的Module已经具备了开发uni-app插件的能力了。

编写uni-app插件
- 学习Weex扩展 Android 知识。目前集成了Weex 0.26.0版本！！！如果你之前开发的是老版本代码需要作升级代码操作。 weex扩展API for android
  特别注意uni-app插件目前仅支持Module扩展和Component扩展，暂时不支持Adapter扩展！！！
- 编写插件
  - 插件封装了一个 RichAlertWXModule, 富文本alert弹窗Module。
    代码可参考UniPlugin-Hello-AS工程中的uniplugin_richalert模块。（UniPlugin-Hello-AS工程请在5+SDK中查找）
  - HBuilderX 项目中使用RichAlert示例：
```
// require插件名称  
const dcRichAlert = uni.requireNativePlugin('DCloud-RichAlert');              
// 使用插件  
dcRichAlert.show({  
    position: 'bottom',  
    title: "提示信息",  
    titleColor: '#FF0000',  
    content: "<a href='https://uniapp.dcloud.io/' value='Hello uni-app'>uni-app</a> 是一个使用 Vue.js 开发跨平台应用的前端框架!\n免费的\n免费的\n免费的\n重要的事情说三遍",  
    contentAlign: 'left',  
    checkBox: {  
        title: '不再提示',  
        isSelected: true  
    },  
    buttons: [{  
        title: '取消'  
    },  
    {  
        title: '否'  
    },  
    {  
        title: '确认',  
        titleColor: '#3F51B5'  
    }  
    ]  
}, result => {  
    switch (result.type) {  
        case 'button':  
            console.log("callback---button--" + result.index);  
            break;  
        case 'checkBox':  
            console.log("callback---checkBox--" + result.isSelected);  
            break;  
        case 'a':  
            console.log("callback---a--" + JSON.stringify(result));  
            break;  
        case 'backCancel':  
            console.log("callback---backCancel--");  
            break;  
   }  });  
```
- 目前对weex支持的问题
  - Activity的获取方式。通过mWXSDKInstance.getContext()强转Activity。建议先instanceof Activity判断一下再强转
  - .vue暂时只能使用module形式。component还不支持在.vue下使用
  - .vue下暂时不支持调用JS同步方法，.nvue可以使用。component的使用可参考weex写法**
  - component、module的生命周回调，暂时只支持onActivityDestroy 、onActivityResume 、onActivityPause、onActivityResult其他后续支持。请留意更新！
- 第三方依赖库
  - 均要使用compileOnly依赖方式，打包时需要配置或挪动文件到相关文件夹中。打包插件介绍时会有相关的具体描述！
  - 请参考android平台所有依赖库列表, 编写自己插件时需要查看是否与编译的程序依赖有冲突，防止审核失败或编译失败等问题。
  - 对有些插件需要引用到.so文件，需要特殊配置一下.请参考Android studio添加第三方库和so
  - 代码中用到的JSONObject、JSONArray 要使用com.alibaba.fastjson.JSONArray;com.alibaba.fastjson.JSONObject; 不要使用org.json.JSONObject;org.json.JSONArray 否则造成参数无法正常传递使用等问题。
- 插件编写命名规范
  - 源代码的package中一定要作者标识防止与其他插件冲突导致插件审核失败，无法上传。
    如示例中插件类的“package uni.dcloud.io.uniplugin_richalert;” “dcloud”就是作者标识！
  - Module扩展和Component扩展在引用中的name，需要前缀加入你自己的标识，防止与其他插件名称冲突。
    如示例中的插件“DCloud-RichAlert”！“DCloud”就是标识！

五、本地调试测试插件并运用到uni-app中

本地注册插件
- 第一种方式
  - 在UniPlugin-Hello-AS工程下 “app” Module根目录assets/dcloud_uniplugins.json文件。在moudles节点下添加你要注册的Module 或 Component
- 第二种方式
  - 创建一个实体类并实现AppHookProxy接口，在onCreate函数中添加weex注册相关参数或填写插件需要在启动时初始化的逻辑。
  - 在UniPlugin-Hello-AS工程下 “app” Module根目录assets/dcloud_uniplugins.json文件，在hooksClass节点添加你创建实现AppHookProxy接口的实体类完整名称填入其中即可 (有些需要初始化操作的需求可以在此处添加逻辑，无特殊操作仅使用第一种方式注册即可无需集成AppHookProxy接口)
  - 具体写法如图：
    以上两种方式选一即可
- dcloud_uniplugins.json说明:
  - nativePlugins：插件跟节点可存放多个插件
  - hooksClass：生命周期代理（实现AppHookProxy接口类）格式(完整包名加类名)
  - name : 注册名称，
  - class : module 或 component 实体类完整名称
  - type : module 或 component类型。
```
{  
  "nativePlugins": [  
    {  
      "hooksClass": "uni.dcloud.io.uniplugin_richalert.apphooks",  
      "plugins": [  
        {  
          "type": "module",  
          "name": "DCloud-RichAlert",  
          "class": "uni.dcloud.io.uniplugin_richalert.RichAlertWXModule"  
        }  
      ]  
    }  
  ]  }  
```

本地测试运行带有插件的uni-app

安装最新HbuilderX 大于等于1.4.0.xxxxxx

创建uni-app工程或在已有的uni-app工程编写相关的.nvue 和.vue文件。使用uni-app插件中的module 或 component。

xxx.vue 示例代码（RichAlert为示例）

<template>  
    <view>  
        <button @click="showRichAlert">  
            点击弹出RichAlert  
        </button>  
    </view>  
</template>  
<script>  
    // require插件名称  
    const dcRichAlert = uni.requireNativePlugin('DCloud-RichAlert');  
    export default {  
        methods: {  
            showRichAlert() {  
                // 使用插件  
                dcRichAlert.show({  
                    position: 'bottom',  
                    title: "提示信息",  
                    titleColor: '#FF0000',  
                    content: "<a href='https://uniapp.dcloud.io/' value='Hello uni-app'>uni-app</a> 是一个使用 Vue.js 开发跨平台应用的前端框架!\n免费的\n免费的\n免费的\n重要的事情说三遍",  
                    contentAlign: 'left',  
                    checkBox: {  
                        title: '不再提示',  
                        isSelected: true  
                    },  
                    buttons: [{  
                        title: '取消'  
                    },  
                    {  
                        title: '否'  
                    },  
                    {  
                        title: '确认',  
                        titleColor: '#3F51B5'  
                    }]  
                }, result => {  
                    switch (result.type) {  
                        case 'button':  
                            console.log("callback---button--" + result.index);  
                        break;  
                        case 'checkBox':  
                            console.log("callback---checkBox--" + result.isSelected);  
                        break;  
                        case 'a':  
                            console.log("callback---a--" + JSON.stringify(result));  
                        break;  
                        case 'backCancel':  
                            console.log("callback---backCancel--");  
                        break;  
                   }  
                });  
            }  
        }  
    }  
</script>

选择发行--->原生APP-本地打包--->生成本地打包App资源等待资源生成！

在控制台会输出编译日志，编译成功会给出App资源路径

把APP资源文件放入到UniPlugin-Hello-AS工程下 “app” Module根目录assets/apps/测试工程appid/www对应目录下,再修改assets/data/dcloud_control.xml!修改其中appid=“测试工程appid”!,测试工程UniPlugin-Hello-AS 已有相关配置可参考。具体可查看离线打包。

appid注意一定要统一否则会导致应用无法正常运行！

配置"app"Module下的 build.gradle. 在dependencies节点添加插件project引用（以uniplugin_richalert为例）
```
// 添加uni-app插件  implementation project(':uniplugin_richalert')    
```