模塊開發(fā)指南_Android_Eclipse

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

第一章 SDK簡介

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

一個完整的SDK包命名類似：ModulesDevProject_Android.zip。解壓后是一個標準的Eclipse工程目錄，如圖所示：

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

第二章 閱讀對象

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

第三章 SDK功能說明

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

i.框架設計

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

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

ii. 主要功能

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

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

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

-module.json文件的聲明

• 往當前屏幕window中插入/移除一個或者多個自定義View，包括：

-直接插入View至window

-獲取一個Activity的View并插入window

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

-直接啟動Activity

-啟動Activity并獲取返回值

• 啟動widget、向window注入Javascript，包括：

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

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

• 擴展模塊項目資源ID的管理，包括：

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

-R文件對應的資源文件ID由引擎負責管理

• 擴展模塊生命周期的管理：

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

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

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

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ā)幫助參考：

詳細的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進行模塊開發(fā)

i. 導入SDK工程到Eclipse

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

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

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

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

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

函數(shù)聲明格式：

public void jsmethod_func(final UZModuleContextmoduleContext){


}

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

如下圖中的定義：

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

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

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

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

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

注意：

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

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

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

UZModuleContext類是JS與原生（Java）之間通信的運行時上下文封裝，既是JS提交給Java數(shù)據(jù)的載體，同時也是Java回調(diào)JS的執(zhí)行者。UZModuleContext內(nèi)部封裝了JSON數(shù)據(jù)操作的所有方法，如optInt、optString等，UZModuleContext同時還封裝了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與原生之間遵循異步訪問機制，Java做完相關(guān)操作后，應該將操作結(jié)果回調(diào)給JS，或者通知JS本次操作成功與否，錯誤提示等。該回調(diào)過程由UZModuleContext下的success、error等函數(shù)完成。如下代碼實現(xiàn)了對“showAlert”結(jié)果的回調(diào)，將用戶點擊對話框按鈕的操作通知JS：

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

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

module.json文件固定存放于assets/uzmap目錄中。 存儲格式為JSON格式，包含modules、name、class等字段。聲明標準如下：

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

字段解釋：

• name：定義該擴展模塊開放給JS的模塊對象名，類似于標準JS中的window、document、Math等對象。
• class：定義該擴展模塊對應綁定至JS的Java類及其路徑。

• 導出模塊包

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

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

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

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

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

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

本SDK默認展示5個擴展模塊demo。其中：

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

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

詳細注釋圖：

• moduleRefresh演示如何進行下拉刷新模塊的開發(fā)。
• moduleScrollPicture演示如何進行UI類模塊的開發(fā)，并實現(xiàn)了類似UIScrollPicture模塊的輪播圖效果功能。
• eventdemo演示如何使用ApplicationDelegate類監(jiān)聽整個應用的生命周期，并進行相關(guān)的操作。
• syncInterface樣式如何進行同步API的擴展。

第七章 SDK主要API簡介

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

i.類

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

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

ii.重要API

APIModule(UZModule)對象：

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

UZModuleContext對象：

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

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

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

目錄解釋：

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

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

（3）、target目錄：用于存放本模塊用到的so動態(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ī)范細則（未處理）。結(jié)構(gòu)如下圖所示：

（5）、module.json文件，其內(nèi)容必須類似如下：

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

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

{
"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模塊為例）：
命名一個布局資源文件：
mo_moduledemo_demo_activity_layout.xml


命名一個圖片資源文件：
mo_moduledemo_backbtn_press_bg.png
mo_moduledemo_layout_bg.png


命名一個字符資源文件：
mo_moduledemo_init_msg
mo_moduledemo_error_msg

ii.引擎固有資源說明

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

ii.其他說明

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

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

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