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格式資料操作等。
三、前期準備
- 安裝JDKversion>=1.7 並配置了環境變數
- 安裝Android SDK 並配置環境變數。
- 安裝Android Studio 儘量使用最新版本！下載地址：Android Studio官網ORAndroid 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; } });
- 外掛 封裝了一個 RichAlertWXModule, 富文字alert彈窗Module。
- 目前對weex支援的問題
- 第三方依賴庫
- 均要使用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”就是標識！
- 原始碼的package中一定要作者標識防止與其他外掛衝突導致外掛稽核失敗，無法上傳。
- 學習Weex擴充套件 Android 知識。目前集成了Weex 0.26.0版本！！！ 如果你之前開發的是老版本程式碼需要作升級程式碼操作。weex擴充套件API for android
五、本地除錯測試外掛並運用到uni-app中
-
本地註冊外掛
- 第一種方式
- 在UniPlugin-Hello-AS工程下 “app” Module根目錄assets/dcloud_uniplugins.json檔案。 在moudles節點下 新增你要註冊的Module 或 Component
- 第二種方式
-
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 外掛資訊
- android檔案 裡面存放XXX.aar 、libs資料夾。
- 生成提交外掛市場的.ZIP包
- 注意：.os檔案需要注意 armeabi-v7a、x86 、arm64-v8a以上三種類型的.so必須要有，如果沒有無法正常使用！！
- 本地uni-app原生外掛提交雲端打包
七、如果想要共享給其他開發者，把這個外掛提交外掛市場
不提交外掛市場，也可以在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實現外掛。