模块开发指南_Android_Studio

第一章 SDK简介

第二章 阅读对象

第三章 SDK功能说明

• 框架设计
• 主要功能

第四章 开发前准备

• 开发环境
• 开发帮助参考

第五章 使用SDK进行模块开发

• 导入SDK工程到Android Studio
• 开始开发模块

第六章 模块开发Demo简介

第七章 SDK主要API简介

• 类
• 重要API

第八章 模块包特别说明

第九章 其他

• 模块资源文件命名规范
• 其他说明

第十章 模块审核规范

参考视频：docs.apicloud.com/APICloud/videos-and-codes

第一章 SDK简介

AndroidStudio版模块包是标准的AAR包。APICloud模块扩展SDK是基于DeepEngine（以下称引擎）开放的一套标准化扩展机制，用于支持开发者灵活扩展任意原生功能到APICloud平台。 平台现有的模块如果无法满足您的需求，可通过该SDK进行模块扩展，在多个项目中复用，为应用开发节省大量的重复性工作，您也可以将开发完成的模块提交到模块商店，分享给开发者使用。 本SDK提供给有一定Android原生开发基础的开发者，通过简单的接口实现和标准的Android开发流程，快速扩展模块，轻松接入APICloud平台。

一个完整的SDK包命名类似：ModulesDevProject_Android.zip。解压后是一个标准的Android Studio工程目录，如图所示：

第二章 阅读对象

本文档面向所有使用该SDK的Android开发人员、测试人员、合作伙伴以及对此感兴趣的其他用户。阅读该文档要求用户熟悉Android应用开发，熟悉Android Studio开发工具的基本使用，并且对Html、CSS、Javascript有一定了解，熟悉Java和Javascript中JSON格式数据的操作。

第三章 SDK功能说明

本SDK是开发者快速了解使用APICloud跨平台移动应用开发引擎，并熟练掌握模块开发技巧及了解APICloud移动应用云平台的桥梁。

i.框架设计

引擎通过实现对操作系统底层能力的封装和扩展，基于H5引擎开放API给JS调用的形式，实现了HTML+CSS+JS开发语言和Object-C/Java/C/C++等原生开发语言之间的桥接，极大的丰富和增强了标准H5的能力。令前端开发者通过JS即可调用移动设备的底层功能，如：电话、短信、定位、多媒体、跨域http请求等，并能将如百度地图、支付宝等第三方厂商的SDK很容易的集成至App中来。

本SDK开放桥接机制，方便具有一定Android基础的开发者灵活扩展模块，丰富JS的能力，提升App的用户体验。引擎框架桥接层设计如图：

ii. 主要功能

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

• 映射一个Java类的函数和常量（统称为模块module）至Javascript对象的函数和常量，包括：

  -被映射Java类的函数、属性及常量书写规范

  -module.json文件的声明

• 往当前屏幕window中插入/移除一个或者多个自定义View，包括：

  -直接插入View至window

  -获取一个Activity的View并插入window

• 在module中启动另一个Activity或App并获取回调，包括：

  -直接启动Activity

  -启动Activity并获取返回值

• 启动widget、向window注入Javascript，包括：

  -在module中调用引擎的widget管理能力启动widget

  -向APP的某活动window注入并执行一段Javascript

• 扩展模块生命周期的管理：

  -动态初始化和分配内存

  -生命周期事件回调等

第四章 开发前准备

i. 开发环境：

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

Android Studio2.3及以上；

Gradle2.3.0及以上（对应官方gradle-3.3-all.zip）。建议提前下载好Gradle，并在开发工具中设置使用本地离线的Gradle；

Android SDK 21（5.0）及以上；

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

ii. 开发帮助参考：

详细的SDK帮助文档：docs.apicloud.com/superwebview/Android/

Android在线API文档：https://developer.android.google.cn/reference/packages.html

Javascript规范及入门：http://www.w3school.com.cn

JSON数据在线Viewer：http://www.bejson.com/go.html?u=http://www.bejson.com/jsonview2/

第五章 使用SDK进行模块开发

i. 导入SDK工程到Android Studio

• 解压ModulesDevProject_Android.zip至任意目录

• 在Android Studio中导入该SDK，操作步骤：Studio ->File ->Oepn ->选择1中解压的目录 ->Ok即可。

将项目管理视图切换为“project”，导入后的工程结构如图：

ii. 开始开发模块

1.创建模块

APICloud模块包为标准的AAR包，遵循Studio的模块开发流程。在项目APICloudModuleSDK上右键 ->New ->Module，为项目新建一个Module，并命名为moduleDemo，如图：

创建完毕后项目结构如图：

2.在项目中配置引用模块

在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进行引用，即仅依赖引用，但不会被编译到AAR中

如图：

4.创建用于绑定映射至JS对象的Java类

在moduleDemo模块中新建Java类（以下以APIModuleDemo.java类为例，映射的JS对象为moduleDemo），继承自引擎Jar包中的APIModule或者UZModule类，并重写相关函数。如下图：

5.在模块声明文件module.json中声明Java类

开发者务必在module.json文件中声明被映射Java类的class路径，以及其所开放给JS的模块名称，引擎将根据该配置检索相应的Java类，并在适当时候将其初始化。

module.json文件固定存放于app下的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类及其路径。

6.定义开放API

若希望将Java类中的某个函数开放给JS调用，只需将该函数声明以“jsmethod_”开头，并且声明该函数为public，同时接收且仅接收一个类型为UZModuleContext的参数即可。

函数声明格式：

public void jsmethod_func(final UZModuleContextmoduleContext){

}

引擎会在初始化的时候，根据Java函数是否包含“jsmethod_”的前缀，而将该函数映射至JS对象。例如声明“jsmethod_showAlert”，引擎会将“jsmethod_showAlert”函数映射至模块对应JS对象的“showAlert”函数，开发者在Html页面中即可使用moduleDemo.showAlert(argument)的方式直接调用至Java的jsmethod_showAlert函数，并进行相关操作。

如下图中的定义：

实现了向JS对象映射：

• showAlert：弹出一个对话框，接收定义为“msg”字段的参数作为对话内容；

对应在JS中使用：

• moduleDemo.showAlert(argument)；

即可调用到对应的Java函数中；

注意：

以“jsmethod_”前缀声明的Java函数，引擎默认在UI线程中操作该函数，因此请勿在该函数内部做耗时的操作，避免引起UI阻塞，抛出异常，耗时操作可另起线程进行。

7.获取来自JS传入的参数

扩展机制规范要求前端JS开发者必须使用JSON格式数据作为JS与原生（Java）之间交换数据的传参。引擎将对JS传入的参数进行处理并封装，通过包装成UZModuleContext类传递给声明“jsmethod_”前缀的函数。

UZModuleContext类是JS与原生（Java）之间通信的运行时上下文封装，既是JS提交给Java数据的载体，同时也是Java回调JS的执行者。UZModuleContext内部封装了JSON数据操作的所有方法，如optInt、optString等，UZModuleContext同时还封装了success、error等回调JS的方法。

例如Html页面代码为：

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

在Java中可通过类似如下方式获取JS传入的msg值：

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

8.将操作结果回调至JS

JS与原生之间遵循异步访问机制，Java做完相关操作后，应该将操作结果回调给JS，或者通知JS本次操作成功与否，错误提示等。该回调过程由UZModuleContext下的success、error等函数完成。如下代码实现了对“showAlert”结果的回调，将用户点击对话框按钮的操作通知JS：

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

导出模块包

模块开发调试完毕后，需将该模块编译为AAR包，并按照APICloud模块包要求打包，通过APICloud网站控制台提交。 打包步骤：

• 将当前项目焦点聚在将要导出的模块上，并在工具栏依次操作Build ->Make Module 'xxxModule'。如下图：

• 编译完毕，进入该模块的build/outputs/aar/目录，将其中的“xxxModule-release.aar”文件拷贝。如图：

• 新建文件夹，命名为你的模块名，比如“moduleDemo”，将“xxxModule-release.aar”粘贴至该文件夹，同时在该目录下新建名为“module.json”的json文件，并将app中声明的模块配置拷贝到该文件中，例如：

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

• 最终模块包结构如图：

• 如果你的模块还依赖其他AAR，也需要将这些AAR复制粘贴至该文件夹，包含到模块包里。例如，你的模块依赖support-vector-drawable-24.0.0.aar，最终模块包目录文件将如图所示：

• 将“moduleDemo”文件夹压缩为标准zip格式的文件：

• 通过APICloud网站控制台上传自定义模块即可使用：

第六章 模块开发Demo简介

本SDK默认展示5个扩展模块demo。其中：

• moduleDemo演示一个扩展模块的完整过程。扩展一个名为moduleDemo的JS对象，并将该对象映射至Java类（APIModuleDemo）的过程，同时展示如何在html页面中通过JS调用该模块。APIModuleDemo类下每个API都有详细注释及使用实例，请开发者仔细阅读，同时请关注assets/widget目录下html页面的书写内容。

• moduleRefresh演示如何进行下拉刷新模块的开发。

• moduleScrollPicture演示如何进行UI类模块的开发，并实现了类似UIScrollPicture模块的轮播图效果功能。

• eventdemo演示如何使用ApplicationDelegate类监听整个应用的生命周期，并进行相关的操作。

• syncInterface样式如何进行同步API的扩展。

第七章 SDK主要API简介

本章节提供引擎所有与模块扩展相关的API说明。

i.类

本SDK开放数个关键类：APIModule(UZModule)、ApplicationDelegate、UZModuleContext、ModuleResult、RefreshHeader，以及若干工具类API及常量，如：UZUtility、APICloudHttpClient等。

ii.重要API

APIModule(UZModule)对象：

UZModuleContext对象：

第八章 模块包特别说明

• 模块应将其所依赖的所有外部资源尽量包含在AAR中，避免通过compile引用

• module.json文件，其内容必须如下：

  {
  "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.资源文件命名规范

建议开发者在开发过程中对资源文件的命名遵循如下规则：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

特别说明：SDK工程目录下的任意原有资源文件，开发者不应随意改动，需保持其原状，否则SDK可能在启动过程中报找不到引擎资源的警告而强制退出，或者破坏模块开发环境与云编译环境的一致性。

ii.其他说明

在开始模块开发之前，建议阅读《开发模块设计规范》。

第十章 模块审核规范

开发者开发的模块务必遵守《模块审核规范-Android》。