模块开发设计规范-H5

H5模块背景

  APICloud平台通过可复用的跨平台引擎和模块，为APP开发节省了大量的工作。开发者在使用平台进行APP开发时，以编写H5代码为主，辅以原生模块和引擎API，经过长期的实践我们发现，除了引擎和模块本身，一个APP中至少有50%的H5代码，也是可以在另一个APP中直接或者进行少量改动后复用的，但因为APP都属于不同的开发者，彼此之间无法沟通，缺乏复用的桥梁。

  因此我们希望在平台现有的模块生态下，新增H5类型模块，为开发者建立H5代码复用的桥梁。该类型模块要求提交H5源码，该源码可以是某个功能的抽象封装，比如操作数据库；可以是某个效果的封装，比如日历效果；也可以是功能加效果的封装，比如基于融云模块的聊天列表等等。开发者通过平台获取到该模块的源码后，可以在自身APP中直接使用。

  以下规范旨在统一H5模块的的标准和形式，同时帮助审核人员提高审核效率，保证模块品质。

1.模块规范

  H5模块应包为独立的可直接在标准手机浏览器或者APICloud环境下运行的代码，包含Html、CSS、 JS代码以及所依赖的图片等资源文件和帮助文档。模块应遵循简洁，抽象，低耦合的原则，避免冗余的CSS/JS代码，不建议提供基于VUE、JQ等框架的模块。 网络请求必须用api.ajax。

1.1 模块包及结构

  H5模块包须遵守如下包结构及文件命名规范。

1.1.1 包结构

  模块包整体结构如下，最外层以模块名作为根目录，其下包含image，libs等子目录，其中，html和readme.md为必须项。

  1. module_name 
  2. ├─ image
  3. ├─ libs
  4. │  ├─ xxx.js
  5. ├─ module_name.html 
  6. ├─ module_name.css
  7. ├─ module_name.js
  8. ├─ readme.md

文件及目录解释：

  ─module_name：模块包根目录，以模块名命名

  ─image：[可选] 存放本模块引用的图片资源

  ─libs：[可选] 存放本模块依赖第三方框架，JS库等，比如VUE

  ─module_name.html：[必需] 本模块的html页。可以是模块入口文件，比如日历效果模块，也可以是test文件，比如功能型的非UI类操作封装，需要提供运行CASE；也可以是模块的html/css/js代码同时包含在该文件中

  ─readme.md：[必需] 本模块的说明文档。提供该模块的使用帮助说明，依赖哪些Android&IOS模块说明等

  ─module_name.css：[可选] 本模块抽出的CSS样式

  ─module_name.js：[可选] 本模块抽出的JS代码

1.1.2 readme.md文件特别说明

  readme.md文件为本模块的整体说明及使用帮助文件，需遵守如下规范：

  （1）应清晰描述本模块的使用流程及开放的API或者可改动哪些代码实现定制等

  （2）如果你的H5模块是基于某个原生模块封装的操作，比如基于rongCloud2模块封装的对话列表及对话窗口功能，需在该文档首部声明本模块依赖rongCloud2模块

  （3）readme.md文件基本格式：

  1. # 功能描述
  3.     描述…
  5. # 依赖的模块
  7.     module1、module2 …
  9. # 快速使用
  11.     使用流程描述，API描述，代码更改定制帮助等…
  13. # 特别说明
  15.     使用本模块需要特别注意的地方，或者可能存在哪些问题，技术支持、帮助信息等

1.2 命名规范

  对于Html/CSS/JS资源及编码的命名规范，开发者可以遵循一些公开公认的规范，也可以遵循团队内部自定义的规范，本章节建议的命名规范，目的在于通过统一的标准，尽可能的避免模块之间的冲突。 另外需要遵循《代码加密规范》中命名规则：https://docs.apicloud.com/Dev-Guide/Code-Specification

1.2.1 资源命名

  拒绝使用汉字或者大写字母命名资源，同时建议开发者在开发过程中对本模块使用到的资源文件的命名遵循如下规则，避免与其他模块命名相同而导致文件被覆盖。

  命名规则：mo（或任意自定义前缀） + 模块名 + 资源名

  例如（以moduledemo模块为例）：

  （1）命名一个图片资源文件：

    mo_moduledemo_tabicon_1.png

  （2）命名一个CSS样式文件：

    mo_moduledemo.css

    mo_moduledemo_btn.css

  （3）命名一个JS文件：

    mo_moduledemo_toast.js

    mo_moduledemo_alert.js

1.2.2 CSS样式命名

  对于CSS样式选择器的命名，应增加类似于资源命名的前缀，避免与其他模块样式产生命名冲突而导致样式失效。

  以下为建议的CSS样式命名方式：

  1. .mo-md-body{
  3. }
  5. #mo-md-title{
  7. }
  9. #mo-md-title > div{
  11. }

  其中，md为moduledemo的简写。或者您可以自定义任意字符。

1.2.3 JS函数命名

  对于JS函数的命名，应增加类似于资源命名的前缀，避免与其他模块函数产生命名冲突而导致代码执行失败或者报错。

  以下为建议的JS函数命名方式：

  1. function moMdToast(msg){
  3. }
  5. function moMdAlert(msg){
  7. }

  其中，md为moduledemo的简写。或者您可以自定义任意字符。

2.审核标准

  参见《模块审核规范-H5》