模塊開發(fā)指南_Android_Studio

參考視頻：docs.apicloud.com/APICloud/videos-and-codes

第一章 SDK簡(jiǎn)介

AndroidStudio版模塊包是標(biāo)準(zhǔn)的AAR包。APICloud模塊擴(kuò)展SDK是基于DeepEngine（以下稱引擎）開放的一套標(biāo)準(zhǔn)化擴(kuò)展機(jī)制，用于支持開發(fā)者靈活擴(kuò)展任意原生功能到APICloud平臺(tái)。 平臺(tái)現(xiàn)有的模塊如果無(wú)法滿足您的需求，可通過(guò)該SDK進(jìn)行模塊擴(kuò)展，在多個(gè)項(xiàng)目中復(fù)用，為應(yīng)用開發(fā)節(jié)省大量的重復(fù)性工作，您也可以將開發(fā)完成的模塊提交到模塊商店，分享給開發(fā)者使用。 本SDK提供給有一定Android原生開發(fā)基礎(chǔ)的開發(fā)者，通過(guò)簡(jiǎn)單的接口實(shí)現(xiàn)和標(biāo)準(zhǔn)的Android開發(fā)流程，快速擴(kuò)展模塊，輕松接入APICloud平臺(tái)。

一個(gè)完整的SDK包命名類似：ModulesDevProject_Android.zip。解壓后是一個(gè)標(biāo)準(zhǔn)的Android Studio工程目錄，如圖所示：

第二章 閱讀對(duì)象

本文檔面向所有使用該SDK的Android開發(fā)人員、測(cè)試人員、合作伙伴以及對(duì)此感興趣的其他用戶。閱讀該文檔要求用戶熟悉Android應(yīng)用開發(fā)，熟悉Android Studio開發(fā)工具的基本使用，并且對(duì)Html、CSS、Javascript有一定了解，熟悉Java和Javascript中JSON格式數(shù)據(jù)的操作。

第三章 SDK功能說(shuō)明

本SDK是開發(fā)者快速了解使用APICloud跨平臺(tái)移動(dòng)應(yīng)用開發(fā)引擎，并熟練掌握模塊開發(fā)技巧及了解APICloud移動(dòng)應(yīng)用云平臺(tái)的橋梁。

i.框架設(shè)計(jì)

引擎通過(guò)實(shí)現(xiàn)對(duì)操作系統(tǒng)底層能力的封裝和擴(kuò)展，基于H5引擎開放API給JS調(diào)用的形式，實(shí)現(xiàn)了HTML+CSS+JS開發(fā)語(yǔ)言和Object-C/Java/C/C++等原生開發(fā)語(yǔ)言之間的橋接，極大的豐富和增強(qiáng)了標(biāo)準(zhǔn)H5的能力。令前端開發(fā)者通過(guò)JS即可調(diào)用移動(dòng)設(shè)備的底層功能，如：電話、短信、定位、多媒體、跨域http請(qǐng)求等，并能將如百度地圖、支付寶等第三方廠商的SDK很容易的集成至App中來(lái)。

本SDK開放橋接機(jī)制，方便具有一定Android基礎(chǔ)的開發(fā)者靈活擴(kuò)展模塊，豐富JS的能力，提升App的用戶體驗(yàn)。引擎框架橋接層設(shè)計(jì)如圖：

ii. 主要功能

本SDK主要提供以下功能和接口：

• 映射一個(gè)Java類的函數(shù)和常量（統(tǒng)稱為模塊module）至Javascript對(duì)象的函數(shù)和常量，包括：

-被映射Java類的函數(shù)、屬性及常量書寫規(guī)范

-module.json文件的聲明

• 往當(dāng)前屏幕window中插入/移除一個(gè)或者多個(gè)自定義View，包括：

-直接插入View至window

-獲取一個(gè)Activity的View并插入window

• 在module中啟動(dòng)另一個(gè)Activity或App并獲取回調(diào)，包括：

-直接啟動(dòng)Activity

-啟動(dòng)Activity并獲取返回值

• 啟動(dòng)widget、向window注入Javascript，包括：

-在module中調(diào)用引擎的widget管理能力啟動(dòng)widget

-向APP的某活動(dòng)window注入并執(zhí)行一段Javascript

• 擴(kuò)展模塊生命周期的管理：

-動(dòng)態(tài)初始化和分配內(nèi)存

-生命周期事件回調(diào)等

第四章 開發(fā)前準(zhǔn)備

i. 開發(fā)環(huán)境：

PC：Windows XP/Win7/8/10 Mac OS；

JDK1.8及以上，默認(rèn)使用1.8；

Android Studio3.0及以上；

Gradle5.6.4及以上（對(duì)應(yīng)官方gradle-5.6.4-all.zip），Gradle插件版本3.6.1。建議提前下載好Gradle，并在開發(fā)工具中設(shè)置使用本地離線的Gradle；

Android SDK 21（5.0）及以上，建議使用30；

Android Studio下載地址：https://developer.android.google.cn/studio/index.html

ii. 開發(fā)幫助參考：

詳細(xì)的SDK幫助文檔：docs.apicloud.com/superwebview/Android/（未處理）

Android在線API文檔:https://developer.android.google.cn/reference/packages.html

Javascript規(guī)范及入門：http://www.w3school.com.cn（未處理）

JSON數(shù)據(jù)在線Viewer：http://www.bejson.com/go.html?u=http://www.bejson.com/jsonview2/(未處理)

第五章 使用SDK進(jìn)行模塊開發(fā)

i. 導(dǎo)入SDK工程到Android Studio

• 解壓ModulesDevProject_Android.zip至任意目錄
• 在Android Studio中導(dǎo)入該SDK，操作步驟：Studio ->File ->Oepn ->選擇1中解壓的目錄 ->Ok即可。

將項(xiàng)目管理視圖切換為“project”，導(dǎo)入后的工程結(jié)構(gòu)如圖：

ii. 開始開發(fā)模塊

1.創(chuàng)建模塊

APICloud模塊包為標(biāo)準(zhǔn)的AAR包，遵循Studio的模塊開發(fā)流程。在項(xiàng)目APICloudModuleSDK上右鍵 ->New ->Module，為項(xiàng)目新建一個(gè)Module，并命名為moduleDemo，如圖：

創(chuàng)建完畢后項(xiàng)目結(jié)構(gòu)如圖：

2.在項(xiàng)目中配置引用模塊

在app的build文件中配置引用moduleDemo模塊，操作步驟：打開app ->build.gradle，在dependencies中加入引用

compile project(':moduleDemo')

如圖：

3.在模塊中配置引用引擎jar包

在moduleDemo模塊的build文件中配置引用引擎的jar包，操作步驟：打開moduleDemo ->build.gradle，在dependencies中加入引用

provided files('../app/libs/apiEngine v1.1.0.jar')

注意：使用provided進(jìn)行引用，即僅依賴引用，但不會(huì)被編譯到AAR中

如圖：

4.創(chuàng)建用于綁定映射至JS對(duì)象的Java類

在moduleDemo模塊中新建Java類（以下以APIModuleDemo.java類為例，映射的JS對(duì)象為moduleDemo），繼承自引擎Jar包中的APIModule或者UZModule類，并重寫相關(guān)函數(shù)。如下圖：

5.在模塊聲明文件module.json中聲明Java類

開發(fā)者務(wù)必在module.json文件中聲明被映射Java類的class路徑，以及其所開放給JS的模塊名稱，引擎將根據(jù)該配置檢索相應(yīng)的Java類，并在適當(dāng)時(shí)候?qū)⑵涑跏蓟?/p>

module.json文件固定存放于app下的assets/uzmap目錄中，如圖：

存儲(chǔ)格式為JSON格式，包含modules、name、class等字段。聲明標(biāo)準(zhǔn)如下：

{
    "modules":[
        {
        "name":"moduleDemo",
        "class":"com.apicloud.moduleDemo.APIModuleDemo"
        },
        {
        "name":"xxxDemo",
        "class":"com.xxx.Objxxx"
        },
        {
        "name":"xxxDemo1",
        "class":"com.xxx.Objxxx1"
        }
    ]
}

字段解釋：

• name：定義該擴(kuò)展模塊開放給JS的模塊對(duì)象名，類似于標(biāo)準(zhǔn)JS中的window、document、Math等對(duì)象。
• class：定義該擴(kuò)展模塊對(duì)應(yīng)綁定至JS的Java類及其路徑。

6.定義開放API

若希望將Java類中的某個(gè)函數(shù)開放給JS調(diào)用，只需將該函數(shù)聲明以“jsmethod_”開頭，并且聲明該函數(shù)為public，同時(shí)接收且僅接收一個(gè)類型為UZModuleContext的參數(shù)即可。

函數(shù)聲明格式：

public void jsmethod_func(final UZModuleContextmoduleContext){


}

引擎會(huì)在初始化的時(shí)候，根據(jù)Java函數(shù)是否包含“jsmethod_”的前綴，而將該函數(shù)映射至JS對(duì)象。例如聲明“jsmethod_showAlert”，引擎會(huì)將“jsmethod_showAlert”函數(shù)映射至模塊對(duì)應(yīng)JS對(duì)象的“showAlert”函數(shù)，開發(fā)者在Html頁(yè)面中即可使用moduleDemo.showAlert(argument)的方式直接調(diào)用至Java的jsmethod_showAlert函數(shù)，并進(jìn)行相關(guān)操作。

如下圖中的定義：

實(shí)現(xiàn)了向JS對(duì)象映射：

• showAlert：彈出一個(gè)對(duì)話框，接收定義為“msg”字段的參數(shù)作為對(duì)話內(nèi)容；

對(duì)應(yīng)在JS中使用：

• moduleDemo.showAlert(argument)；

即可調(diào)用到對(duì)應(yīng)的Java函數(shù)中；

注意：

以“jsmethod_”前綴聲明的Java函數(shù)，引擎默認(rèn)在UI線程中操作該函數(shù)，因此請(qǐng)勿在該函數(shù)內(nèi)部做耗時(shí)的操作，避免引起UI阻塞，拋出異常，耗時(shí)操作可另起線程進(jìn)行。

7.獲取來(lái)自JS傳入的參數(shù)

擴(kuò)展機(jī)制規(guī)范要求前端JS開發(fā)者必須使用JSON格式數(shù)據(jù)作為JS與原生（Java）之間交換數(shù)據(jù)的傳參。引擎將對(duì)JS傳入的參數(shù)進(jìn)行處理并封裝，通過(guò)包裝成UZModuleContext類傳遞給聲明“jsmethod_”前綴的函數(shù)。

UZModuleContext類是JS與原生（Java）之間通信的運(yùn)行時(shí)上下文封裝，既是JS提交給Java數(shù)據(jù)的載體，同時(shí)也是Java回調(diào)JS的執(zhí)行者。UZModuleContext內(nèi)部封裝了JSON數(shù)據(jù)操作的所有方法，如optInt、optString等，UZModuleContext同時(shí)還封裝了success、error等回調(diào)JS的方法。

例如Html頁(yè)面代碼為：

uzmoduledemo.showAlert({msg:"Hello APICloud!"});

在Java中可通過(guò)類似如下方式獲取JS傳入的msg值：

public void jsmethod_showAlert(final UZModuleContext moduleContext){
    String showMsg = moduleContext.optString("msg");
}

8.將操作結(jié)果回調(diào)至JS

JS與原生之間遵循異步訪問(wèn)機(jī)制，Java做完相關(guān)操作后，應(yīng)該將操作結(jié)果回調(diào)給JS，或者通知JS本次操作成功與否，錯(cuò)誤提示等。該回調(diào)過(guò)程由UZModuleContext下的success、error等函數(shù)完成。如下代碼實(shí)現(xiàn)了對(duì)“showAlert”結(jié)果的回調(diào)，將用戶點(diǎn)擊對(duì)話框按鈕的操作通知JS：

JSONObject ret = new JSONObject();
try {
    ret.put("buttonIndex", 1);
} catch (JSONException e) {
    e.printStackTrace();
}
moduleContext.success(ret, true);

ii. 導(dǎo)出模塊包

1.導(dǎo)出模塊包

模塊開發(fā)調(diào)試完畢后，需將該模塊編譯為AAR包，并按照APICloud模塊包要求打包，通過(guò)APICloud網(wǎng)站控制臺(tái)提交。 打包步驟：

• 將當(dāng)前項(xiàng)目焦點(diǎn)聚在將要導(dǎo)出的模塊上，并在工具欄依次操作Build ->Make Module 'xxxModule'。如下圖：

• 編譯完畢，進(jìn)入該模塊的build/outputs/aar/目錄，將其中的“xxxModule-release.aar”文件拷貝。如圖：

• 新建文件夾，命名為你的模塊名，比如“moduleDemo”，將“xxxModule-release.aar”粘貼至該文件夾，同時(shí)在該目錄下新建名為“module.json”的json文件，并將app中聲明的模塊配置拷貝到該文件中，例如：

  {
  "name":"moduleDemo",
  "class":"com.apicloud.moduleDemo.APIModuleDemo"
  }

• 最終模塊包結(jié)構(gòu)如圖：

• 如果你的模塊還依賴其他AAR，也需要將這些AAR復(fù)制粘貼至該文件夾，包含到模塊包里。例如，你的模塊依賴support-vector-drawable-24.0.0.aar，最終模塊包目錄文件將如圖所示：

• 將“moduleDemo”文件夾壓縮為標(biāo)準(zhǔn)zip格式的文件：

• 通過(guò)APICloud網(wǎng)站控制臺(tái)上傳自定義模塊即可使用：

第六章 模塊開發(fā)Demo簡(jiǎn)介

本SDK默認(rèn)展示5個(gè)擴(kuò)展模塊demo。其中：

• moduleDemo演示一個(gè)擴(kuò)展模塊的完整過(guò)程。擴(kuò)展一個(gè)名為moduleDemo的JS對(duì)象，并將該對(duì)象映射至Java類（APIModuleDemo）的過(guò)程，同時(shí)展示如何在html頁(yè)面中通過(guò)JS調(diào)用該模塊。APIModuleDemo類下每個(gè)API都有詳細(xì)注釋及使用實(shí)例，請(qǐng)開發(fā)者仔細(xì)閱讀，同時(shí)請(qǐng)關(guān)注assets/widget目錄下html頁(yè)面的書寫內(nèi)容。
• moduleRefresh演示如何進(jìn)行下拉刷新模塊的開發(fā)。
• moduleScrollPicture演示如何進(jìn)行UI類模塊的開發(fā)，并實(shí)現(xiàn)了類似UIScrollPicture模塊的輪播圖效果功能。
• eventdemo演示如何使用ApplicationDelegate類監(jiān)聽整個(gè)應(yīng)用的生命周期，并進(jìn)行相關(guān)的操作。
• syncInterface樣式如何進(jìn)行同步API的擴(kuò)展。

第七章 SDK主要API簡(jiǎn)介

本章節(jié)提供引擎所有與模塊擴(kuò)展相關(guān)的API說(shuō)明。

i.類

本SDK開放數(shù)個(gè)關(guān)鍵類：APIModule(UZModule)、ApplicationDelegate、UZModuleContext、ModuleResult、RefreshHeader，以及若干工具類API及常量，如：UZUtility、APICloudHttpClient等。

類	描述
APIModule(UZModule)	所有擴(kuò)展模塊的基類，Java類通過(guò)繼承該類并聲明相應(yīng)函數(shù)，實(shí)現(xiàn)Java類綁定映射至JS對(duì)象，并開放API
UZModuleContext	JS函數(shù)映射至Java函數(shù)時(shí)，傳遞參數(shù)的載體，同時(shí)也是Java回調(diào)結(jié)果至JS的執(zhí)行者。包含操作標(biāo)準(zhǔn)JSON的方法
ApplicationDelegate	應(yīng)用生命周期的回調(diào)代理類?？赏ㄟ^(guò)定義類繼承實(shí)現(xiàn)該類，并在module.json中配置聲明，實(shí)現(xiàn)對(duì)應(yīng)用生命周期的監(jiān)聽。
ModuleResult	模塊同步接口，返回結(jié)果時(shí)的包裝類。模塊開放同步接口時(shí)，在使用"sync"標(biāo)識(shí)某接口為同步接口的同時(shí)，該接口需將數(shù)據(jù)結(jié)果通過(guò)ModuleResult包裝后返回
RefreshHeader	下拉刷新頭模塊的父類，所有下拉刷新頭類的模塊，必須繼承該類，并實(shí)現(xiàn)相關(guān)函數(shù)，同時(shí)必須在module.json中配置該類。
UZUtility	基礎(chǔ)工具類，定義了許多實(shí)用函數(shù)，如獲取外部存儲(chǔ)路徑，相對(duì)/絕對(duì)路徑轉(zhuǎn)換等
UZResourcesIDFinder	動(dòng)態(tài)獲取資源ID的工具類。在模塊開發(fā)過(guò)程中不允許直接通過(guò)引用R文件進(jìn)行資源引用，必須通過(guò)本類下的接口動(dòng)態(tài)獲取資源ID
APICloudHttpClient	api.ajax（http、https）的原生API，管理所有請(qǐng)求，支持get、post、delete、download等常見操作，支持同步請(qǐng)求，取消等功能?？芍苯诱{(diào)用，實(shí)現(xiàn)遠(yuǎn)程數(shù)據(jù)的獲取，圖片異步下載，資源緩存等

ii.重要API

APIModule(UZModule)對(duì)象：

API	描述
runOnUiThread	在UI線程中執(zhí)行操作
startActivityForResult	啟動(dòng)一個(gè)Activity并要求返回值。所有使用APICloud SDK擴(kuò)展的模塊，在需要startActivityForResult時(shí)，都必須調(diào)用該接口，而不能直接調(diào)Activity的startActivityForResult
getFeatureValue	獲取當(dāng)前應(yīng)用widget的config文件中feature字段的值
insertViewToCurWindow	插入一個(gè)自定義的View到當(dāng)前window中
removeViewFromCurWindow	從當(dāng)前window移除某個(gè)自定義View
makeRealPath	將一個(gè)任意協(xié)議的路徑，如標(biāo)準(zhǔn)的content://，res://，以及APICloud擴(kuò)展的widget://，fs://，cache://轉(zhuǎn)換為系統(tǒng)可識(shí)別的真實(shí)路徑
inImmerseState	當(dāng)前app是否處于"沉浸式"效果下。
onActivityResult	通過(guò)startActivityForResult時(shí)，回調(diào)結(jié)果可重寫此接口獲取
getContext	獲取運(yùn)行時(shí)上下文
getSecureValue	獲取當(dāng)前應(yīng)用widget的key.xml文件中字段的值。
onClean	引擎主動(dòng)回調(diào)函數(shù)，當(dāng)window或者frame關(guān)閉以及當(dāng)前頁(yè)面發(fā)生url變化時(shí)，引擎會(huì)主動(dòng)回調(diào)該接口，開發(fā)者應(yīng)該在此接口中清理當(dāng)前模塊占用的資源，如網(wǎng)絡(luò)資源，內(nèi)存資源等

UZModuleContext對(duì)象：

API	描述
success	模塊正?；卣{(diào)結(jié)果給JS
error	當(dāng)模塊內(nèi)部發(fā)生異常時(shí)，通過(guò)此接口回調(diào)結(jié)果給JS
interrupt	不處理回調(diào)。建議模塊開發(fā)中，不想處理回調(diào)JS時(shí)，調(diào)用一下該函數(shù)
opt*	各種操作JSON數(shù)據(jù)的方法

第八章 模塊包特別說(shuō)明

• 模塊應(yīng)將其所依賴的所有外部資源盡量包含在AAR中，避免通過(guò)compile或implementation引用

• module.json文件，其內(nèi)容必須如下：

  {
  "name":"moduleDemo",
  "class":"com.apicloud.moduleDemo.APIModuleDemo"
  }

如果一個(gè)模塊包中包含多個(gè)模塊入口，則配置類似如下：

  {
  "name":"moduleDemo",
  "class":"com.apicloud.moduleDemo.APIModuleDemo"
  },
  {
  "name":"moduleDemo1",
  "class":"com.demo.ModuleDemo1"
  },
  {
  "name":"moduleDemo2",
  "class":"com.demo.ModuleDemo2"
  }

ii. 模塊兼容AndroidX

• APICloud云編譯依賴的android支持庫(kù)默認(rèn)為support-v4:26.0.0版本，如果您的模塊希望依賴androidx作為支持庫(kù)，則需要在模塊導(dǎo)出的aar中增加相應(yīng)的標(biāo)識(shí)。 具體做法：在相應(yīng)模塊AndroidManifest.xml的manifest節(jié)點(diǎn)下增加name為“android.useAndroidX”的meta-data，并將value置為true，如下圖所示。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.apicloud.sdk.moduledemo">


    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="28"/>


    <uses-permission android:name="android.permission.VIBRATE" />


    <meta-data android:name="android.useAndroidX" android:value="true" />


    <application>


    </application>


</manifest>

云編譯在獲得模塊該標(biāo)識(shí)后，將自動(dòng)為當(dāng)前所編譯項(xiàng)目增加androidx支持庫(kù)。

特別說(shuō)明：如果模塊依賴androidx，將觸發(fā)apk依賴庫(kù)從support遷移到androidx，對(duì)用戶編譯的apk可能存在潛在風(fēng)險(xiǎn)，應(yīng)在模塊文檔中明確告知模塊使用者。

第九章 其他

i.資源文件命名規(guī)范

建議開發(fā)者在開發(fā)過(guò)程中對(duì)資源文件的命名遵循如下規(guī)則：mo + 模塊名 + 功能或UI類型 + 資源類型。

例如（以moduleDemo模塊為例）：
命名一個(gè)布局資源文件：
mo_moduledemo_demo_activity_layout.xml


命名一個(gè)圖片資源文件：
mo_moduledemo_backbtn_press_bg.png
mo_moduledemo_layout_bg.png


命名一個(gè)字符資源文件：
mo_moduledemo_init_msg
mo_moduledemo_error_msg

特別說(shuō)明：SDK工程目錄下的任意原有資源文件，開發(fā)者不應(yīng)隨意改動(dòng)，需保持其原狀，否則SDK可能在啟動(dòng)過(guò)程中報(bào)找不到引擎資源的警告而強(qiáng)制退出，或者破壞模塊開發(fā)環(huán)境與云編譯環(huán)境的一致性。

ii.其他說(shuō)明

在開始模塊開發(fā)之前，建議閱讀《開發(fā)模塊設(shè)計(jì)規(guī)范》（未處理）。

第十章 模塊審核規(guī)范

開發(fā)者開發(fā)的模塊務(wù)必遵守《模塊審核規(guī)范-Android》（未處理）。