uniapp安卓原生組件開發

https://ask.dcloud.net.cn/article/35416

項目需要基於uniapp 開發原生組件 。

 

一、簡介

本文檔介紹如何在uni-app中基於weexsdk 開發Android原生插件。
更多說明請參考uni-app原生插件開發指南。

二、開發者須知

在您閱讀此文檔時，我們假定您已經具備了相應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') 

  • 運行測試。測試運行時一切要以真機運行為主。

六、打包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必須要有，如果沒有無法正常使用！！
• 本地uni-app原生插件提交雲端打包

七、如果想要共享給其他開發者，把這個插件提交插件市場

• 提交插件到DCloud插件市場

不提交插件市場，也可以在HBuilderX里提交雲端打包。

關於第三方庫引用問題：

• 盡量去下載相關的aar或jar，然后配置到插件包相應文件夾下。aar放到android目錄下。jar放到libs目錄下。如果不下載也可以。可使用compileOnly修飾，然后將相應的依賴庫名稱配置到package.json中的dependencies節點下。

• 第三方庫依賴沖突。一種是主app已完整集成相關第三方庫。可使用用compileOnly修飾即可。如果主app僅集成了部分第三方庫。可參考https://blog.csdn.net/wapchief/article/details/80514880

• .os文件需要注意 armeabi-v7a、x86 、arm64-v8a以上三種類型的.so必須要有，如果沒有無法正常使用！！

• 插件中包含FileProvider雲打包沖突，可通過http://ask.dcloud.net.cn/article/36105此貼配置繞過。

• 插件中有資源路徑返回時，請使用絕對路徑file://開頭防止不必要的路徑轉換問題。

• androidx暫時不支持。請使用v4、v7實現插件。