模塊開發(fā)指南_Android_Eclipse

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

第一章 SDK簡介

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

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

備注：其中readme.txt是與版本描述相關(guān)的說明文件。

第二章 閱讀對象

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

第三章 SDK功能說明

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

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

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

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

ii. 主要功能

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

• 映射一個(gè)Java類的函數(shù)和常量（統(tǒng)稱為模塊module）至Javascript對象的函數(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ò)展模塊項(xiàng)目資源ID的管理，包括：

-引擎及所有模塊中均不允許出現(xiàn)R文件的引用。

-R文件對應(yīng)的資源文件ID由引擎負(fù)責(zé)管理

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

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

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

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

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

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

Eclipse3.7及以上；

ADT21及以上；

Android SDK 21（5.0）及以上；

JDK1.6或者1.7。盡量不要使用1.8，存在各種潛在問題；

其中Android環(huán)境推薦使用Google整合版的Eclipse：SDK ADT Bundle;

下載地址：http://developer.android.com/sdk/index.html#download（Google已廢棄，可通過其他途徑下載，或者使用Studio）

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工程到Eclipse

• 解壓ModulesDevProject_Android.zip至任意目錄
• 在Eclipse中導(dǎo)入該SDK，操作步驟：Eclipse ->File ->Import ->General ->Existing Project into Workspace ->Browser ->選擇1中解壓的目錄 ->Finish即可

導(dǎo)入后的工程結(jié)構(gòu)如圖：

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

• 新建用于綁定映射至JS對象的Java類。在項(xiàng)目中新建Java類（以下以APIModuleDemo.java類為例，映射的JS對象為moduleDemo），繼承自引擎Jar包中的APIModule或者UZModule類，并重寫相關(guān)函數(shù)。如下圖：

• 定義開放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對象。例如聲明“jsmethod_showAlert”，引擎會(huì)將“jsmethod_showAlert”函數(shù)映射至模塊對應(yīng)JS對象的“showAlert”函數(shù)，開發(fā)者在Html頁面中即可使用moduleDemo.showAlert(argument)的方式直接調(diào)用至Java的jsmethod_showAlert函數(shù)，并進(jìn)行相關(guān)操作。

如下圖中的定義：

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

• showAlert：彈出一個(gè)對話框，接收定義為“msg”字段的參數(shù)作為對話內(nèi)容；
• startActivity：啟動(dòng)一個(gè)Activity；
• startActivityForResult：啟動(dòng)一個(gè)Activity并要求返回值；
• vibrate：調(diào)用設(shè)備震動(dòng)器震動(dòng)；

這四個(gè)函數(shù)，在JS中使用：

• moduleDemo.showAlert(argument)；
• moduleDemo.startActivity(argument)；
• moduleDemo.startActivityForResult(argument)；
• moduleDemo.vibrate(argument)；

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

注意：

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

• 獲取來自JS傳入的參數(shù)。

擴(kuò)展機(jī)制規(guī)范要求前端JS開發(fā)者必須使用JSON格式數(shù)據(jù)作為JS與原生（Java）之間交換數(shù)據(jù)的傳參。引擎將對JS傳入的參數(shù)進(jìn)行處理并封裝，通過包裝成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頁面代碼為：

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

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

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

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

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

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

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

module.json文件固定存放于assets/uzmap目錄中。 存儲格式為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的模塊對象名，類似于標(biāo)準(zhǔn)JS中的window、document、Math等對象。
• class：定義該擴(kuò)展模塊對應(yīng)綁定至JS的Java類及其路徑。

• 導(dǎo)出模塊包

模塊開發(fā)調(diào)試完畢后，需要將你的代碼及資源按照APICloud模塊結(jié)構(gòu)要求導(dǎo)出成模塊包（zip格式），通過APICloud網(wǎng)站控制臺提交。

• 模塊包結(jié)構(gòu)預(yù)覽

見第八章 模塊包結(jié)構(gòu)說明（未處理）

• 導(dǎo)出模塊包操作關(guān)鍵步驟：

    （1）導(dǎo)出所有代碼與你模塊相關(guān)的代碼文件到j(luò)ar包里。操作步驟：File -> Export ->JAR file ->勾選需要導(dǎo)出代碼及目錄，next即可。如果有需要導(dǎo)出的assets資源，在可在該步驟勾選，將其導(dǎo)出到j(luò)ar包里；
    （2）從工程res目錄中分離出所有與你的模塊相關(guān)的資源文件，且不改變其所在目錄;
    （3）從工程AndroidManifest文件中分離出你的模塊所定義的任何activity、service、provider、permission等;
    （4）將1、2、3步驟得到的文件按照模塊包結(jié)構(gòu)說明復(fù)制到moduleDemo目錄下對應(yīng)目錄中;
    （5）將moduleDemo目錄壓縮成zip格式包;

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

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

• moduleDemo演示一個(gè)擴(kuò)展模塊的完整過程。擴(kuò)展一個(gè)名為moduleDemo的JS對象，并將該對象映射至Java類（APIModuleDemo）的過程，同時(shí)展示如何在html頁面中通過JS調(diào)用該模塊。

APIModuleDemo類下每個(gè)API都有詳細(xì)注釋及使用實(shí)例，請開發(fā)者仔細(xì)閱讀，同時(shí)請關(guān)注assets/widget目錄下html頁面的書寫內(nèi)容。

詳細(xì)注釋圖：

• 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é)提供引擎所有與模塊擴(kuò)展相關(guān)的API說明。

i.類

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

類	描述
APIModule(UZModule)	所有擴(kuò)展模塊的基類，Java類通過繼承該類并聲明相應(yīng)函數(shù)，實(shí)現(xiàn)Java類綁定映射至JS對象，并開放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)代理類?？赏ㄟ^定義類繼承實(shí)現(xiàn)該類，并在module.json中配置聲明，實(shí)現(xiàn)對應(yīng)用生命周期的監(jiān)聽。
ModuleResult	模塊同步接口，返回結(jié)果時(shí)的包裝類。模塊開放同步接口時(shí)，在使用"sync"標(biāo)識某接口為同步接口的同時(shí)，該接口需將數(shù)據(jù)結(jié)果通過ModuleResult包裝后返回
RefreshHeader	下拉刷新頭模塊的父類，所有下拉刷新頭類的模塊，必須繼承該類，并實(shí)現(xiàn)相關(guān)函數(shù)，同時(shí)必須在module.json中配置該類。
UZUtility	基礎(chǔ)工具類，定義了許多實(shí)用函數(shù)，如獲取外部存儲路徑，相對/絕對路徑轉(zhuǎn)換等
APICloudHttpClient	api.ajax（http、https）的原生API，管理所有請求，支持get、post、delete、下載等常見操作，支持同步請求，取消等?？芍苯诱{(diào)用，實(shí)現(xiàn)遠(yuǎn)程數(shù)據(jù)的獲取，圖片異步下載，資源緩存等

ii.重要API

APIModule(UZModule)對象：

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í)路徑
inImmerseState	當(dāng)前app是否處于"沉浸式"效果下。
onActivityResult	通過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)前頁面發(fā)生url變化時(shí)，引擎會(huì)主動(dòng)回調(diào)該接口，開發(fā)者應(yīng)該在此接口中清理當(dāng)前模塊占用的資源，如網(wǎng)絡(luò)資源，內(nèi)存資源等

UZModuleContext對象：

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

第八章 模塊包結(jié)構(gòu)說明

一個(gè)模塊包根目錄以該模塊的JS對象名命名（以下以moduleDemo為例），二級子目錄通常包含如下圖目錄結(jié)構(gòu)：

目錄解釋：

（1）、res_xxxx目錄：xxx為您的擴(kuò)展模塊名。該目錄與Android項(xiàng)目中的資源文件目錄res目錄及結(jié)構(gòu)保持一致，包含drawable、layout、values等子目錄。在模塊包中，該目錄下只需對應(yīng)存放你的模塊中用到的資源文件即可。詳情見資源規(guī)范細(xì)則（未處理）。結(jié)構(gòu)類似下圖：

（2）、source目錄：存放你的代碼導(dǎo)出的jar包，依賴的jar包，以及相關(guān)源代碼的目錄，如jar、java、c、cpp等文件。如下圖：

（3）、target目錄：用于存放本模塊用到的so動(dòng)態(tài)庫文件。如下圖：

特別說明：armeabi架構(gòu)的so直接放到target根目錄（必須的），其他架構(gòu)的so連同目錄放置在target下（如果沒有提供armeabi的so，則將armeabi-v7a的放置在target根目錄）。target目錄最終的結(jié)構(gòu)如下：

target/libxxx.so
target/armeabi-v7a/libxxx.so
target/x86/libxxx.so
target/arm64-v8a/libxxx.so
...

（4）、AndroidManifest.xml文件：存放你的模塊中用到的權(quán)限，定義的activity，service，provider等清單組件。詳情見資源規(guī)范細(xì)則（未處理）。結(jié)構(gòu)如下圖所示：

（5）、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"
}

第九章 其他

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

建議開發(fā)者在開發(fā)過程中對資源文件的命名遵循如下規(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

ii.引擎固有資源說明

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

ii.其他說明

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

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

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