DCloud_Android_ST
DCloud_Android_ST
  • 发布:2018-12-26 18:09
  • 更新:2019-11-19 09:06
  • 阅读:44955

Android uni-app原生插件开发文档

分类:uni-app

uni-app原生插件开发教程 Android Studio 版

一、简介

本文档介绍如何在uni-app中基于weexsdk 开发Android原生插件。
更多说明请参考uni-app原生插件开发指南

二、开发者须知

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

三、前期准备

四、插件开发

  • 导入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文件在打插件包时文件到底放在什么位置请留意插件打包文档。
      注意:v4v7已升级到26.1.0 图片还是25版本 请留意并修改

    • 加入以下引用(出现底色标红表示当前引用版本与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.20.0版本!!! 如果你之前开发的是老版本代码需要作升级代码操作。 weex官方文档
      特别注意uni-app插件目前仅支持Module扩展和Component扩展,暂时不支持Adapter扩展!!!
    • 编写插件

      • 插件 封装了一个 RichAlertWXModule, 富文本alert弹窗Module。

        代码可参考UniPlugin-Hello-AS里的uniplugin_richalert Module
      • 使用介绍

        // 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。
    • 选择 发行--->原生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')    
    • 运行测试。测试运行时一切要以真机运行为主。

六、打包uni-app插件

  • 选择Gradle--->插件module--->Tasks--->build--->assembleRelease编译module的aar文件
    注意:新版本Android studio将assembleRelease放入other中了
  • 将编译依赖库文件或仓储代码放入libs目录下或配置到package.json中
  • package.json填写必要的信息
  • 完整的android 插件包包含:
    • android文件 里面存放XXX.aar 、libs文件夹。
      • .aar文件 插件包
      • libs文件夹 存放插件包依赖的第三方 .jar文件和.so文件
    • package.json 插件信息
  • 生成提交插件市场的.ZIP包
    • 一级目录以插件id命名,对应package.json中的id字段! 存放android文件夹和package.json文件。
    • 二级目录 android 存放安卓插件 .aar 文件 .jar .so放入到libs下
  • 注意:.os文件需要注意 armeabi-v7a、x86 、arm64-v8a以上三种类型的.so必须要有,如果没有无法正常使用!!

七、如果想要共享给其他开发者,把这个插件提交插件市场

不提交插件市场,也可以在HBuilderX里提交云端打包。

关于第三方库引用问题:

  • 尽量去下载相关的aar或jar,然后配置到插件包相应文件夹下。aar放到android目录下。jar放到libs目录下。如果不下载也可以。可使用compileOnly修饰,然后将相应的依赖库名称配置到package.json中的dependencies节点下。

  • 第三方库依赖冲突。一种是主app已完整集成相关第三方库。可使用用compileOnly修饰即可。如果主app仅集成了部分第三方库。可参考https://blog.csdn.net/wapchief/article/details/80514880

  • 插件中包含FileProvider云打包冲突,可通过http://ask.dcloud.net.cn/article/36105此贴配置绕过。

  • 插件中有资源路径返回时,请使用绝对路径file://开头防止不必要的路径转换问题。

欢迎有原生开发能力的朋友入群一起交流学习(入群请提供注册邮箱):
DCloud原生开发者群:
1群:256775471(已满)
2群:814228233(已满)
3群:455763866

iOS原生插件开发参考:https://ask.dcloud.net.cn/article/35415
更多uni-app原生插件文档参考:uni-app原生插件开发指南

6 关注 分享
Trust 诗小柒 1361810132@qq.com 师大酸梅杨 86300845@qq.com jzq84229

要回复文章请先登录注册

asdfasfsa

asdfasfsa

这么复杂,不如直接搞原生吧
2019-11-19 09:06
caesar000

caesar000

没人说这文档写得相当绕吗 ?
2019-11-13 14:07
943112965@qq.com

943112965@qq.com

我要集成穿山甲广告sdk 怎么做啊。好复杂的样子
2019-09-30 11:43
zyfking@hotmail.com

zyfking@hotmail.com

谁能提供一个Androidx uni-app的离线插件例子没有?
2019-09-27 14:18
hou110yuan@163.com

hou110yuan@163.com

回复 低价位小菜:
问下怎么弄的,官方文档看起来太吃力了
2019-09-19 17:09
sewenfengqing@163.com

sewenfengqing@163.com

基于weexsdk 开发Android原生插件,而不是基于weeksdk 开发Android原生插件,累。。。
2019-08-16 14:54
sewenfengqing@163.com

sewenfengqing@163.com

回复 sewenfengqing@163.com:
在Manifest.json也选择本地native Plugin,但是调用的使用提醒undefined
2019-08-05 16:59
sewenfengqing@163.com

sewenfengqing@163.com

插件包已经打包完成,但是uniapp中调用报错:undefined is not an object (evaluating 'myPlugin.testMethod1'); [Component] Event Handler Error @ pages/index/index#handleEvent
2019-08-05 16:57
低价位小菜

低价位小菜

y已经写好的安卓原生demo可以转换成uni-app插件么
2019-08-01 10:10
708911156@qq.com

708911156@qq.com

我用官方demo UniPlugin-Hello-AS打包uniplugin_richalert-release.aar只有16k,而且还不能用,请问怎么打包?
2019-07-25 19:55