模塊開(kāi)發(fā)設計規范-H5

H5模塊背景

??APICloud平臺通過(guò)可復用的跨平臺引擎和模塊，為APP開(kāi)發(fā)節省了大量的工作。開(kāi)發(fā)者在使用平臺進(jìn)行APP開(kāi)發(fā)時(shí)，以編寫(xiě)H5代碼為主，輔以原生模塊和引擎API，經(jīng)過(guò)長(cháng)期的實(shí)踐我們發(fā)現，除了引擎和模塊本身，一個(gè)APP中至少有50%的H5代碼，也是可以在另一個(gè)APP中直接或者進(jìn)行少量改動(dòng)后復用的，但因為APP都屬于不同的開(kāi)發(fā)者，彼此之間無(wú)法溝通，缺乏復用的橋梁。

??因此我們希望在平臺現有的模塊生態(tài)下，新增H5類(lèi)型模塊，為開(kāi)發(fā)者建立H5代碼復用的橋梁。該類(lèi)型模塊要求提交H5源碼，該源碼可以是某個(gè)功能的抽象封裝，比如操作數據庫；可以是某個(gè)效果的封裝，比如日歷效果；也可以是功能加效果的封裝，比如基于融云模塊的聊天列表等等。開(kāi)發(fā)者通過(guò)平臺獲取到該模塊的源碼后，可以在自身APP中直接使用。

??以下規范旨在統一H5模塊的的標準和形式，同時(shí)幫助審核人員提高審核效率，保證模塊品質(zhì)。

1.模塊規范

??H5模塊應包為獨立的可直接在標準手機瀏覽器或者APICloud環(huán)境下運行的代碼，包含Html、CSS、JS代碼以及所依賴(lài)的圖片等資源文件和幫助文檔。模塊應遵循簡(jiǎn)潔，抽象，低耦合的原則，避免冗余的CSS/JS代碼，不建議提供基于VUE、JQ等框架的模塊。網(wǎng)絡(luò )請求必須用api.ajax。

1.1 模塊包及結構

??H5模塊包須遵守如下包結構及文件命名規范。

1.1.1 包結構

??模塊包整體結構如下，最外層以模塊名作為根目錄，其下包含image，libs等子目錄，其中，html和readme.md為必須項。

module_name ├─ image├─ libs│  ├─ xxx.js├─ module_name.html ├─ module_name.css├─ module_name.js├─ readme.md

文件及目錄解釋?zhuān)?/p>

??─module_name：模塊包根目錄，以模塊名命名

??─image：[可選]?存放本模塊引用的圖片資源

??─libs：[可選]?存放本模塊依賴(lài)第三方框架，JS庫等，比如VUE

??─module_name.html：[必需]?本模塊的html頁(yè)?？梢允悄K入口文件，比如日歷效果模塊，也可以是test文件，比如功能型的非UI類(lèi)操作封裝，需要提供運行CASE；也可以是模塊的html/css/js代碼同時(shí)包含在該文件中

??─readme.md：[必需]?本模塊的說(shuō)明文檔。提供該模塊的使用幫助說(shuō)明，依賴(lài)哪些Android&IOS模塊說(shuō)明等

??─module_name.css：[可選]?本模塊抽出的CSS樣式

??─module_name.js：[可選]?本模塊抽出的JS代碼

1.1.2 readme.md文件特別說(shuō)明

??readme.md文件為本模塊的整體說(shuō)明及使用幫助文件，需遵守如下規范：

??（1）應清晰描述本模塊的使用流程及開(kāi)放的API或者可改動(dòng)哪些代碼實(shí)現定制等

??（2）如果你的H5模塊是基于某個(gè)原生模塊封裝的操作，比如基于rongCloud2模塊封裝的對話(huà)列表及對話(huà)窗口功能，需在該文檔首部聲明本模塊依賴(lài)rongCloud2模塊

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

# 功能描述    描述…# 依賴(lài)的模塊    module1、module2 …# 快速使用    使用流程描述，API描述，代碼更改定制幫助等…# 特別說(shuō)明    使用本模塊需要特別注意的地方，或者可能存在哪些問(wèn)題，技術(shù)支持、幫助信息等

1.2 命名規范

??對于Html/CSS/JS資源及編碼的命名規范，開(kāi)發(fā)者可以遵循一些公開(kāi)公認的規范，也可以遵循團隊內部自定義的規范，本章節建議的命名規范，目的在于通過(guò)統一的標準，盡可能的避免模塊之間的沖突。另外需要遵循《代碼加密規范》中命名規則：https://docs.apicloud.com/Dev-Guide/Code-Specification

1.2.1 資源命名

??拒絕使用漢字或者大寫(xiě)字母命名資源，同時(shí)建議開(kāi)發(fā)者在開(kāi)發(fā)過(guò)程中對本模塊使用到的資源文件的命名遵循如下規則，避免與其他模塊命名相同而導致文件被覆蓋。

??命名規則：mo（或任意自定義前綴） + 模塊名 + 資源名

??例如（以moduledemo模塊為例）：

??（1）命名一個(gè)圖片資源文件：

????mo_moduledemo_tabicon_1.png

??（2）命名一個(gè)CSS樣式文件：

????mo_moduledemo.css

????mo_moduledemo_btn.css

??（3）命名一個(gè)JS文件：

????mo_moduledemo_toast.js

????mo_moduledemo_alert.js

1.2.2 CSS樣式命名

??對于CSS樣式選擇器的命名，應增加類(lèi)似于資源命名的前綴，避免與其他模塊樣式產(chǎn)生命名沖突而導致樣式失效。

??以下為建議的CSS樣式命名方式：

.mo-md-body{}#mo-md-title{}#mo-md-title > div{}

??其中，md為moduledemo的簡(jiǎn)寫(xiě)?；蛘吣梢宰远x任意字符。

1.2.3 JS函數命名

??對于JS函數的命名，應增加類(lèi)似于資源命名的前綴，避免與其他模塊函數產(chǎn)生命名沖突而導致代碼執行失敗或者報錯。

??以下為建議的JS函數命名方式：

function moMdToast(msg){}function moMdAlert(msg){}