Web前端開發規範文檔

時間 2019-11-30

標籤 web 前端開發規範文檔欄目 HTML 简体版

原文原文鏈接

通用規範：

TAB鍵用4個空格代替（WINDOWS下TAB鍵佔四個空格，LINUX下TAB鍵佔八個空格;通常用4個空格代替tab，vim，eclipse，np++等均可以設置）。javascript

CSS樣式屬性或者JAVASCRIPT代碼後加「;」方便壓縮工具「斷句」。css

文件內容編碼均統一爲UTF-8。html

CSS、JAVASCRIPT中的非註釋類中文字符須轉換成unicode編碼使用,以免編碼錯誤時亂碼顯示。java

這段代碼演示了JavaScript中字符串與Unicode編碼的轉換:jquery

// 爲了控制檯的演示方便, 變量沒有添加 var 定義 // 實際編程中請避免 // 字符串
str = "中文"; // 獲取字符
char0 = str.charAt(0); // "中" // 數字編碼值
code = str.charCodeAt(0); // 20013 // 編碼互轉
str0 = String.fromCharCode(code); // "中" // 轉爲16進制數組
code16 = code.toString(16); // "4e2d" // 變成字面量表示法
ustr = "\\u"+code16; // "\u4e2d" // 包裝爲JSON
jsonstr = '{"ustr": "'+ ustr +'"}'; //'{"ustr": "\u4e2d"}' // 使用JSON工具轉換
obj = JSON.parse(jsonstr); // Object {ustr: "中"} // ustr_n = obj.ustr; // "中"

文件規範：

文件名用英文單詞，多個單詞用駝峯命名法。web

一些瀏覽器會將含有這些詞的做爲廣告攔截，文件命名、ID、CLASS等全部命名避免以上詞彙。chrome

`ad`、`ads`、`adv`、`banner`、`sponsor`、`gg`、`guangg`、`guanggao` 等typescript

html書寫規範：

爲每一個HTML頁面的第一行添加標準模式（standard mode）的聲明，確保在每一個瀏覽器中擁有一致的展示。express

<!DOCTYPE html>編程

文檔類型聲明統一爲HTML5聲明類型，編碼統一爲UTF-8。

<HEAD>中添加信息。

<meta name="author" content="smile@kang.cool">//做者 <meta name="description" content="hello">//網頁描述 <meta name="keywords" content="a,b,c">//關鍵字,「，」分隔 <meta http-equiv="expires" content="Wed, 26 Feb 1997 08：21：57 GMT">//設定網頁的到期時間。一旦網頁過時，必須到服務器上從新調閱 <meta http-equiv="Pragma" content="no-cache">//禁止瀏覽器從本地機的緩存中調閱頁面內容 <meta http-equiv="Window-target" content="_top">//用來防止別人在框架裏調用你的頁面 <meta http-equiv="Refresh" content="5;URL=http://kahn1990.com/">//跳轉頁面，5指時間停留5秒 網頁搜索機器人嚮導。用來告訴搜索機器人哪些頁面須要索引，哪些頁面不須要索引 <meta name="robots" content="none">//content的參數有all,none,index,noindex,follow,nofollow，默認是all <link rel="Shortcut Icon" href="favicon.ico">//收藏圖標 <meta http-equiv="Cache-Control" content="no-cache, must-revalidate">//網頁不會被緩存

IE支持經過特定<meta>標籤來肯定繪製當前頁面所應該採用的IE版本。除非有強烈的特殊需求，不然最好是設置爲edge mode ，從而通知IE採用其所支持的最新的模式。

非特殊狀況下CSS樣式文件外鏈至HEAD之間，JAVASCRIPT文件外鏈至頁面底部。

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="css/main.css">
</head>
<body>
<!-- 邏輯代碼 --> <!-- 邏輯代碼底部 -->
<script src="lib/jquery/jquery-2.1.1.min.js"></script>
</body>
</html>

引入JAVASCRIPT庫文件，文件名須包含庫名稱及版本號及是否爲壓縮版。

jQuery-1.8.3.min.js

引入JAVASCRIPT插件, 文件名格式爲庫名稱+.+插件名稱。

jQuery.cookie.js

HTML屬性應當按照如下給出的順序依次排列，來確保代碼的易讀性。

class id 、 name data-* src、for、 type、 href title、alt aria-*、 role

編碼均遵循XHTML標準,
標籤、屬性、屬性命名由小寫英文、數字和_組成，且全部標籤必須閉合，屬性值必須用雙引號"",
避免使用中文拼音儘可能簡易並要求語義化。

CLASS --> nHeadTitle -->

CLASS遵循小駝峯命名法（little camel-case）

ID --> n_head_title -->

ID遵循名稱+_ NAME --> N_Head_Title -->

NAME屬性命名遵循首個字母大寫+_

<div class="nHeadTitle" id="n_head_title" name="N_Head_Title"></div>

當JAVASCRIPT獲取單個元素時，一般使用document.getElementById來獲取dom元素，document.getElementById兼容全部瀏覽器，但IE瀏覽器會混淆元素的ID和NAME屬性，因此要區分ID和NAME命名。

<input type="text" name="test">
<div id="test"></div>
<button onclick="alert(document.getElementById('test').tagName)"></button>
<!-- ie6下爲INPUT -->

特殊符號應使用轉義字符。

字符	十進制	轉義字符
"	"	"
&	&	&
<	<	<
>	>	>
不斷開空格(non-breaking space)

含有描述性表單元素（INPUT，TEXTAREA）添加LABEL。

<p>
<label for="test">測試</label>
<input type="text" id="test" />
</p>

多用無兼容性問題的HTML內置標籤,
好比SPAN、EM、STRONG、OPTGROUP、LABEL等,須要自定義HTML標籤屬性時，首先考慮是否存在已有的合適標籤可替換，若是沒有,可以使用須以「data-」爲前綴來添加自定義屬性，避免使用其餘命名方式。

語義化 HTML。

儘量減小<DIV>嵌套。

書寫連接地址時避免重定向。

href="http://www.kahn1990.com/" //即在URL地址後面加「/」

HTML中對於屬性的定義，確保所有使用雙引號，毫不要使用單引號

css書寫規範：

爲了欺騙W3C的驗證工具,可將代碼分爲兩個文件，一個是針對全部瀏覽器,一個只針對IE。即將全部符合W3C的代碼寫到一個文件中,而一些IE中必須而又不能經過W3C驗證的代碼（如:
cursor:hand;）放到另外一個文件中，再用下面的方法導入。

<!-- 放置全部瀏覽器樣式-->
<link rel="stylesheet" type="text/css" href="">
<!-- 只放置IE必須，而不能經過w3c的-->
<!--[if IE] <link rel="stylesheet" href=""> <![endif]-->

CSS樣式新建或修改儘可能遵循如下原則。

根據新建樣式的適用範圍分爲三級：全站級、產品級、頁面級。

儘可能經過繼承和層疊重用已有樣式。

不要輕易改動全站級CSS。

改動後，要通過全面測試。

CSS屬性顯示順序。

顯示屬性元素位置元素屬性元素內容屬性

CSS書寫順序。

.header { 
/* 顯示屬性 */ display || visibility list-style position top || right || bottom || left z-index clear float 
/* 自身屬性 */ width max-width || min-width height max-height || min-height overflow || clip margin padding outline border background 
/* 文本屬性 */ color font text-overflow text-align text-indent line-height white-space vertical-align cursor content };

兼容多個瀏覽器時，將標準屬性寫在底部。

-moz-border-radius: 15px; /* Firefox */ 
-webkit-border-radius: 15px; /* Safari和Chrome */ 
border-radius: 15px; /* Opera 10.5+, 以及使用了IE-CSS3的IE瀏覽器 *//標準屬性

使用選擇器時，命名比較短的詞彙或者縮寫的不容許直接定義樣式。

.hd,.bd,.td{};//如這些命名

可用上級節點進行限定。

.recommend-mod .hd

多選擇器規則之間換行，即當樣式針對多個選擇器時每一個選擇器佔一行。

button.btn, input.btn, 
input[type="button"] {…};

優化CSS選擇器。

#header a { color: #444; }; /*CSS選擇器是從右邊到左邊進行匹配*/

瀏覽器將檢查整個文檔中的全部連接和每一個連接的父元素，並遍歷文檔樹去查找ID爲header的祖先元素，若是找不到header將追溯到文檔的根節點，解決方法以下。

避免使用通配規則和相鄰兄弟選擇符、子選擇符,、後代選擇符、屬性選擇符等選擇器

不要限定id選擇符，如div#header（提權的除外）

不要限定類選擇器，如ul.recommend（提權的除外）

不要使用 ul li a 這樣長的選擇符

避免使用標籤子選擇符，如#header > li > a

使用z-index屬性儘可能z-index的值不要超過150（通用組的除外），頁面中的元素內容的z-index不能超過10（提示框等模塊除外但維持在150如下），不容許直接使用（999~9999）之間大值。

儘可能避免使用CSS Hack。

property:value; /* 全部瀏覽器 */ 
+property:value; /* IE7 */ 
_property:value; /* IE6 */ 
*property:value; /* IE6/7 */ 
property:value\9; /* IE6/7/8/9，即全部IE瀏覽器 */ 
* html selector { … }; /* IE6 */ 
*:first-child+html selector { … }; /* IE7 */ 
html>body selector { … }; /* 非IE6 */ 
@-moz-document url-prefix() { … }; /* firefox */ 
@media all and (-webkit-min-device-pixel-ratio:0) { … }; /* saf3+/chrome1+ */ 
@media all and (-webkit-min-device-pixel-ratio:10000),not all and (-webkit-min-device-pixel-ratio:0) { … }; /* opera */ 
@media screen and (max-device-width: 480px) { … }; /* iPhone/mobile webkit */

避免使用低效的選擇器。

body > * {…}; 
ul > li > a {…}; 
#footer > h3 {…}; 
ul#top_blue_nav {…}; 
#searbar span.submit a { … }; /* 反面示例 */

六個不要三個避免一個使用。

不要在標籤上直接寫樣式

不要在CSS中使用expression

不要在CSS中使用 @import

不要在CSS中使用 !important

不要在CSS中使用「*」選擇符

不要將CSS樣式寫爲單行

避免使用 filter

避免使用行內（inline）樣式

避免使用「*」設置 {margin: 0; padding: 0;}

使用 after或overflow的方式清浮動

減小使用影響性能的屬性。

position:absolute; 
float:left; /**如這些定位或浮動屬性**/

減小在CSS中使用濾鏡表達式和圖片repeat,
尤爲在body當中,渲染性能極差, 若是須要用repeat的話,
圖片的寬或高不能少於8px。

協議
不要指定引入資源所帶的具體協議。
當引入圖片或其餘媒體文件，還有樣式和腳本時，URLs 所指向的具體路徑，不要指定協議部分（http:, https:），除非這二者協議都不可用。
不指定協議使得 URL 從絕對的獲取路徑轉變爲相對的，在請求資源協議沒法肯定時很是好用，並且還能爲文件大小節省幾個字節。
不推薦
<script src="http://cdn.com/foundation.min.js"></script>
推薦
<script src="//cdn.com/foundation.min.js"></script>

javaScript書寫規範：

命名規範。

常量名所有大寫並單詞間用下劃線分隔如：CSS_BTN_CLOSE、TXT_LOADING

對象的屬性或方法名小駝峯式（little camel-case）如：init、bindEvent、updatePosition

示例：

Dialog.prototype = { init: function () {}, bindEvent: function () {}, updatePosition: function () {} … };

類名（構造器） -->

小駝峯式但首字母大寫 -->如：Current、DefaultConfig

函數名 -->小駝峯式 -->如：current()、defaultConfig()

變量名 -->小駝峯式 -->如：current、defaultConfig

私有變量名 -->小駝峯式但須要用_開頭 -->如：_current、_defaultConfig

變量名的前綴 -->續

代碼格式。

"()"先後須要跟空格

"="先後須要跟空格

","後面須要跟空格

JSON對象需格式化對象參數

if、while、for、do 語句的執行體用"{}"括起來

"{}"格式以下。

if (a==1) { //代碼 };

避免額外的逗號。

var arr = [1,2,3,];

for-in循環體中必須用hasOwnProperty方法檢查成員是否爲自身成員，避免來自原型鏈上的污染。

長語句可考慮斷行。

TEMPL_SONGLIST.replace('{TABLE}', da['results']) .replace('{PREV_NUM}', prev) 
.replace('{NEXT_NUM}', next) 
.replace('{CURRENT_NUM}', current) 
.replace('{TOTAL_NUM}', da.page_total);

爲了不和JSLint的檢驗機制衝突，「.」或「+」這類操做符放在行尾。

TEMPL_SONGLIST.replace('{TABLE}', da['results']). 
replace('{PREV_NUM}', prev).
replace('{NEXT_NUM}', next). 
replace('{CURRENT_NUM}', current). 
replace('{TOTAL_NUM}', da.page_total);

若是模塊代碼中，使用其它全局變量想跳過JSLint的檢查，能夠在該文件中加入/*global*/聲明。

/*global alert: true, console: true, top: true, setTimeout: true */

使用嚴格的條件判斷符。用===代替==，用!==代替!=，避免掉入==形成的陷阱
在條件判斷時，這樣的一些值表示false。

null

undefined與null相等

字符串''

數字0

NaN

在==時，則會有一些讓人難以理解的陷阱。

(function () { var undefined; undefined == null; // true 
1 == true; //true 
2 == true; // false 
0 == false; // true 
0 == ''; // true 
NaN == NaN;// false 
[] == false; // true 
[] == ![]; // true 
})();

對於不一樣類型的 == 判斷，有這樣一些規則，順序自上而下：

undefined與null相等

一個是number一個是string時，會嘗試將string轉換爲number

嘗試將boolean轉換爲number

0或1

嘗試將Object轉換成number或string

而這些取決於另一個對比量，即值的類型，因此對於0、空字符串的判斷，建議使用=== 。===會先判斷兩邊的值類型，類型不匹配時爲false。

下面類型的對象不建議用new構造。

new Number

new String

new Boolean

new Object //用{}代替

new Array //用[]代替

引用對象成員用obj.prop代替obj["prop"]，除非屬性名是變量。

從number到string的轉換。

/** 推薦寫法*/ 
var a = 1; typeof(a); //"number" 
console.log(a); //1 
var aa=a+''; typeof(aa); //"string" 
console.log(aa); //'1'  /** 不推薦寫法*/ 
new String(a)或a.toString()

從string到number的轉換，使用parseInt，必須顯式指定第二個參數的進制。

/** 推薦寫法*/ 
var a = '1'; var aa = parseInt(a,10); typeof(a); //"string" 
console.log(a); //'1' 
typeof(aa); //"number" 
console.log(aa); //1

從float到integer的轉換。

/** 推薦寫法*/ Math.floor/Math.round/Math.ceil /** 不推薦寫法*/ parseInt

字符串拼接應使用數組保存字符串片斷，使用時調用join方法。避免使用+或+=的方式拼接較長的字符串，每一個字符串都會使用一個小的內存片斷，過多的內存片斷會影響性能。

/**推薦的拼接方式array的push、join*/ 
var str=[], list=['測試A','測試B']; for (var i=0 , len=list.length; i < len; i++) { str.push( '<div>'+ list[i] + '</div>'); }; console.log(str.join('')); //<div>測試A</div><div>測試B</div> /** 不推薦的拼接方式+=*/
var str = '', list=['測試A','測試B']; for (var i = 0, len = list.length; i< len; i++) { str+='<div>' + list[i] + '</div>'; }; console.log(str); //<div>測試A</div><div>測試B</div>

儘可能避免使用存在兼容性及消耗資源的方法或屬性。

不要使用with，void，evil，eval_r，innerText

注重HTML分離, 減少reflow, 注重性能。

圖片規範：

命名應用小寫英文、數字、_組合，便於團隊其餘成員理解。

header_btn.gif header_btn2.gif

頁面元素類圖片均放入img文件夾,測試用圖片放於img/testimg文件夾，psd源圖放入img/psdimg文件夾。

圖片格式僅限於gif、png、jpg等。

用png圖片作圖片時,要求圖片格式爲png-8格式,若png-8實在影響圖片質量或其中有半透明效果,請爲ie-6單獨定義背景，並儘可能避免使用半透明的png圖片。

背景圖片請儘量使用sprite技術, 減少http請求。

註釋規範：

JAVASCRIPT、CSS文件註釋須要標明做者、文件版本、建立/修改時間、重大版本修改記錄、函數描述、文件版本、建立或者修改時間、功能、做者等信息。

/* * 註釋塊 */

中間可添加以下信息。

@file 文件名 @addon 把一個函數標記爲另外一個函數的擴張，另外一個函數的定義不在源文件中 @argument 用大括號中的自變量類型描述一個自變量 @author 函數/類做者的姓名 @base 若是類是繼承得來，定義提供的類名稱 @class 用來給一個類提供描述，不能用於構造器的文檔中 @constructor 描述一個類的構造器 @deprecated 表示函數/類已被忽略 @exception 描述函數/類產生的一個錯誤 @exec @extends 表示派生出當前類的另外一個類 @fileoverview 表示文檔塊將用於描述當前文件，這個標籤應該放在其它任何標籤以前 @final 指出函數/類 @ignore 讓jsdoc忽視隨後的代碼 @link 相似於@link標籤，用於鏈接許多其它頁面 @member 定義隨後的函數爲提供的類名稱的一個成員 @param 用大括號中的參數類型描述一個參數 @private 表示函數/類爲私有，不該包含在生成的文檔中 @requires 表示須要另外一個函數/類 @return 描述一個函數的返回值 @see 鏈接到另外一個函數/類 @throws 描述函數/類可能產生的錯誤 @type 指定函數/成員的返回類型 @version 函數/類的版本號