模塊開發(fā)設(shè)計規(guī)范-H5

H5模塊背景

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

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

??以下規(guī)范旨在統(tǒng)一H5模塊的的標(biāo)準(zhǔn)和形式，同時幫助審核人員提高審核效率，保證模塊品質(zhì)。

1.模塊規(guī)范

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

1.1 模塊包及結(jié)構(gòu)

??H5模塊包須遵守如下包結(jié)構(gòu)及文件命名規(guī)范。

1.1.1 包結(jié)構(gòu)

??模塊包整體結(jié)構(gòu)如下，最外層以模塊名作為根目錄，其下包含image，libs等子目錄，其中，html和readme.md為必須項(xiàng)。

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

文件及目錄解釋：

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

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

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

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

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

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

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

1.1.2 readme.md文件特別說明

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

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

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

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

# 功能描述

    描述…

# 依賴的模塊

    module1、module2 …

# 快速使用

    使用流程描述，API描述，代碼更改定制幫助等…

# 特別說明

    使用本模塊需要特別注意的地方，或者可能存在哪些問題，技術(shù)支持、幫助信息等

1.2 命名規(guī)范

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

1.2.1 資源命名

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

??命名規(guī)則：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樣式選擇器的命名，應(yīng)增加類似于資源命名的前綴，避免與其他模塊樣式產(chǎn)生命名沖突而導(dǎo)致樣式失效。

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

.mo-md-body{

}

#mo-md-title{

}

#mo-md-title > div{

}

??其中，md為moduledemo的簡寫?；蛘吣梢宰远x任意字符。

1.2.3 JS函數(shù)命名

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

??以下為建議的JS函數(shù)命名方式：

function moMdToast(msg){

}

function moMdAlert(msg){

}

??其中，md為moduledemo的簡寫。或者您可以自定義任意字符。

2.審核標(biāo)準(zhǔn)

??參見《模塊審核規(guī)范-H5》