前端開發及相關規范 - 基於gulp的前端框架開發規范
1.前端開發工具的安裝和使用說明
前端開發工具的目錄結構
html
codeBuilder - v0.9
├── statics
├── html //靜態文件開發
├── js // 非require引入的js文件
├── Lib // 第三方JS包
├── ve_2_1 //
├── css // 樣式目錄
├── fonts // bootstrap的圖標字體
├── img // 圖片目錄
├── less // less源碼
├── sprite // 雪碧圖按目錄全稱目錄名的圖片
├── dirName
├── vender // 第三方css包,比如bootstrap
├── js // JS目錄
├── dist //生成文件的目錄(與開發源碼目模塊對應)
├── cart.js
├── common.js
├── lib.js
├── region.js
├── sidebar.js
├── tpl.js
├── user.js
├── web.js
├── src // 開發源碼的目錄
├── cart // 購物車模塊
├── common // 公共的函數模塊
├── lib // 公共jq插件模塊
├── region // 處理聯動地址的模塊
├── sidebar // 側邊欄模塊
├── tpl // 前端mvc模板引擎的壓縮源碼
├── user // 用戶中心模塊
├── web // VE前端模塊，包括首頁、親子、品牌專題、詳情頁等
├── tpl //
├── config.dev.js // requirejs 開發配置文件[自動生成]
├── config.js // requirejs開發配置文件[自動生成]
├── config.release.js //
├── config.test.js // requirejs 測試環境配置文件[自動生成]
├── js.map.json // 壓縮后的文件位置映射[自動生成]
├── path.json // requirejs 的 config -> path 內容，第三包的路徑縮寫配置
├── shim.json // requirejs 的 config -> shim 內容，第三包的依賴申明
├── ver_config.json // 開發、測試、預生產到發布，方便部署靜態資源，而創建的版本和環境變量
├── tpl //
├── toolbar
├── mian.html
├── dot.gif // lazyloading的占位符
├── evc-VE.js // 在線客服的js
├── favicon.ico // 網站的縮略logo
├── README.md // 文檔首頁內容 markdown 語法
├── region.js // 地址
statics/Lib // 第三方JS包 目錄說明
每個包單獨一個文件夾，目的是：方便一個包多版本存放
如：jQuery 的 1.x 跟 2.x ， 2.x 是針對移動版
安裝
- 前往 http://nodejs.org/ 安裝nodeJS
- 注意系統是32位還是64位的，選擇對應的版本
- 如果是windows系統，需自行設置好環境變量，將nodejs的路徑加入到系統的
path環境變量中
- 在終端執行
npm install -g cnpm --registry=http://r.cnpmjs.org- 安裝國內鏡像管理命令--
cnpm - 參考文檔 https://www.npmjs.org/package/cnpm
- 安裝國內鏡像管理命令--
- 在終端執行
npm install -g gulp，安裝gulp全局支持 - 進入前端自動化開發和部署工具的目錄，執行
npm install(使用國外鏡像) 或cnpm install(使用國內鏡像)
-- enjoy --
升級自動化工具
- 進入前端自動化開發和部署工具的目錄，執行
npm install(使用國外鏡像) 或cnpm install(使用國內鏡像)
執行自動化工具
以下操作，需進入
FeBuilder的解壓目錄目錄下執行
gulp- 監控 less 文件變化，自動生成 css
- 監控 js/src 文件變化， 自動在
dist目錄生成對應的壓縮 js - 監控 js/src 文件變化， 自動在
doc目錄，根據jsdoc格式，生成文檔 - 監控
css/sprite目錄，如果有新sns文件，自動生成雪碧圖
注：如果添加新目錄，需重新執行該指令，否則新目錄不會監控
gulp sprite生成雪碧圖gulp script壓縮，合並，打包jsgulp less編譯less文件gulp watch
數據格式約定
- 原則上，前端開發是完全可以脫離開發環境和生產環境來進行的，因為前端開發主要是開發一些靜態的資源，比如
HTML、CSS和JS等。 - 與后端的通訊，我們約定以
JSON的格式進行數據交換，那么前端開發完全就可以本地模擬一個.json格式的文件來進行開發調試。 - 基於
JSON的本地模擬數據，在與后端的同事溝通約定后，只需要對方API返回的數據結構和本地模擬的一致即可。
2.前端開發工具的相關約定
文件和目錄的命名約定
- 必須是英文單詞、名字拼音或者名字拼音首字母;
- 多個單詞用下划線(_)連接;
- 只能出現英文字母、數字、連字符(_)，嚴禁以中文名來命名;
> 注：此命名約定適用於 html, css, js, swf, php, xml, png, gif, jpg, ico 等前端維護的所有文件類型和相關目錄
開發文件的建立
- css
- 基於gulp的前端框架，前端開發是通過編寫LESS，然后gulp會自動監聽LESS來生成壓縮的CSS，生成的文件與LESS同名
- 在 css/less 目錄下建立LESS文件
- 不需要輸出的CSS的，文件名要以下划線 _ 為前綴，通過 @import 包含的方式調用
- 例如: @import "_ve_index";（注意，@import包含的less文件可將.less后綴省略掉）
- 盡管LESS語法兼容CSS語法，但LESS源文件的編寫請遵循LESS語法，以提高它的可讀性和可維護性。
- icon合成雪碧圖 -css sprite
- 在 css/sprite 目錄下，按照功能模塊的不同來建立文件夾，然后將零星的小圖標放置在這個文件夾中；
- 在gulp啟動的狀態下，它會自動監控文件夾中文件的變化，自動合成 css/img/dirName.png 雪碧圖及 css/less/_sp_dirName.less。
- 通過 @import 包含的方式調用 _sp_dirName.less即可
- 請注意，如果一個項目沒有icon，則不要建立一個空的文件夾，gulp會報錯。
什么是CSS Sprites？？
CSS Sprites就是把網頁中一些背景圖片整合到一張圖片文件中，再利用CSS的background-image，background-repeat，background-position的組合進行背景定位，background-position可以用數字精確的定位出背景圖片的位置。利用CSS Sprites能很好地減少網頁的http請求，從而大大的提高頁面的性能，這也是CSS Sprites最大的優點。
-
Javascript
為了項目更容易管理和團隊協作，js的開發需要以模塊化的方式進行。
在ve_2_1/js/src目錄下建立按照功能模塊的不同，來建立文件夾及js文件- js要按照AMD規范來命名和書寫， 通過requireJS包管理器的方式來加載它依賴的其他js模塊；
- js編譯好之后，會自動壓縮到
ve_2_1/js/dist目錄，在頁面中需要配合require.js（js依賴管理）和config.js（依賴的配置文件）來加載自動壓縮后的js。 - config.js有四個不同環境：
config.dev.js、config.test.js、config.release.js和config.js分別對應開發環境、測試環境、預生產環境和生產環境。 - 四個不同環境的js文件加載，在嵌套cms系統的前端模板時，只需要用
{php echo init_js();}(后端php同事要預先封裝好init_js函數)來動態輸出即可。
*** 更多js模塊化開發的參考文檔: - RequireJS和AMD規范
- Javascript模塊化編程1
- Javascript模塊化編程2
- Javascript模塊化編程3
*** 舉例：
ve雙城首頁的js，我們就建立在 js/src/web 目錄下，並命名為index.js，它依賴於'jquery.slide', 'web/common', 'web/timer'和jquery，而'jquery.slide', 'web/common', 'web/timer'也依賴於jqeury，jquery已被全局化，那么index.js應該是這樣的：
index.js:
javascript codeBuilder - v0.9define('web/index', ['jquery.slide', 'web/common', 'web/timer'], function(slide, common) { var doc = document, win = window; //首頁大圖輪播 var _fullSlide = function() { var $sliderBox = $('.slider_box'); var $fullSlide = $('.fullSlide'); var imgs = $fullSlide.find('.bd .preload'); var now_img = $fullSlide.find('.bd img').eq(0); ...又如 common.js應該是這樣的：
common.js:
javascript codeBuilder - v0.9define('web/common', [], function() { var exports = {}; var doc = document, win = window; //網頁頂部的關注hover事件 exports.hover_qr = function() { $('.QRcode').on('mouseover', function() { $('.QRcode-box').toggle(); $('.QRcode i').toggleClass('selected'); }).on('mouseout', function() { $('.QRcode-box').toggle(); $('.QRcode i').toggleClass('selected'); }); }; ...index.js 和common.js不需要在引用
jquery.js,在它們內部中可以直接使用全局jquery中定義的$符號。- 頁面中加載index.js的方法
html codeBuilder - v0.9<script src="http://s1.ve.cn/statics/Lib/require/require.js?_v2.1"> </script><script src="http://s1.ve.cn/statics/Lib/jquery/jquery.min.js?_v2.1"></script> <script src="http://s1.ve.cn/statics/ve_2_1/js/config.js?_1415852637"></script> <!-- requireJS -->
文檔的格式化 - tab制表符來控制縮進
- 無論css、html還是js，開發的源文件都要適當地進行代碼的格式化，一律以tab制表符來控制縮進；
- 調整自己的編輯器，將 tab制表符 以 4個空格 來替代。
> 小技巧：在絕大部分IDE開發工具中， tab是縮進，而shift+tab則是刪除縮進。
3.HTML靜態模板規范
約定
- 所有頁面元素的z-index屬性值控制在1000以下，將1000-2000留給組件級調用，2000以上用於解決特殊情況下的適應問題；
- 所有的標簽及屬性名采用小寫，DOCTYPE除外；
- 保證標簽語義化；
- 分離思想，所有的樣式除特殊情況，css樣式不能內聯寫在style屬性中；
- 如非必要，盡量不采用表格來布局頁面。
- 如非項目需要，不使用html5特有的標簽，如canvas。
頁頭聲明
必須加上以下3項，提高兼容性
html
codeBuilder - v0.9
<meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" /> <meta name="renderer" content="webkit" /> <meta name="viewport" content="width=device-width, initial-scale=1"> 前 2 項，是指定 360 等國產瀏覽器，用 webkit 內核渲染頁面
后 1 項，是在移動端上，指定頁面的縮放比例
HTML注釋
開始和結束均需要帶有可識別的class或id，結束時則加斜杠 /(表示標簽閉合了)。
html
codeBuilder - v0.9
<!-- 商品標題 --> <div class="breadcrumb"> <a href="">唯一優品首頁</a> > <a href="">名品特賣</a> > <a href="">新安怡夏季大促</a> > <a href="" class="title">新安怡 嬰兒保濕潤膚乳液(200ml)</a> </div> <!-- 商品標題end --> css ， js 文件，在頁面上的位置
- 原則上， css 文件， 必須在
<head>內 - 原則上， js 文件， 必須在
</body>結束前（盡可能的放底部），盡情避免在<head>內插入 js
script 標簽是阻塞式加載的。 如果一個 js 文件 比較大，或者 404 ，這將阻塞后面部分內容的加載
標准前端html模板 -- 僅供參考
html
codeBuilder - v0.9
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" /> <meta name="renderer" content="webkit" /> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>{title}</title> <meta name="description" content="{description}" /> <meta name="keywords" content="{keywords}" /> <!-- 樣式文件 --> <link rel="stylesheet" href="./../../ve_2_1/css/ve_wap.css" /> </head> <body> <section class=''> <div class="container"> <div class="row"> a </div> </div> </section> <!-- 尾部js --> <script src="./../../ve_2_1/js/vendor/require/require.js"></script> <script src="./../../ve_2_1/js/config.dev.js"></script> <!-- 替換結束 --> <!-- 自定義代碼部分 --> <script> //js codes here. require(['wap/index'], function() { require(['wap/indexJs']); }); </script> </body> </html> 推薦使用的元素
- 結構元素：blockquote, body, br, div, h1 - h6, head, hr, html, p
- 頭部元素：base, link, meta, script, style, title
- 列表元素：ul, ol, li, dl, dt, dd
- 文本格式元素：a, abbr, acronym, address, bdo, cite, code, del, dfn, em, ins, kbd, noscript, pre, q, samp, small, span, strong, sub, sup, var
- 表單元素：button, fieldset, legend, form, input, label, optgroup, option, select, textarea
- 多媒體元素：area, img, map, object, param
- 表格元素：caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr
- 窗體元素：iframe
不推薦使用的元素
- 結構元素：無
- 頭部元素：無
- 列表元素：dir, menu
- 文本格式元素：b, basefont, big, blink, center, comment, font, i, marquee, nobr, plaintext, ruby, s, strike, u, wbr, xmp
- 表單元素：isindex
- 多媒體元素：applet, bgsound, embed, noembed
- 表格元素：無
- 窗體元素：frame, frameset, noframes
轉世重生的元素
- i - 作為單個圖標的展位符，表示icon
- b - 預留，尚未想到合理的復活理由
- s - 預留，尚未想到合理的復活理由
4.CSS規范
文件編碼約定
- 所有文件一律采用 utf-8編碼
id 和 class 命名約定
- id 和 class 的命名總規則為： 內容優先,表現為輔. 首先根據內容來命名, 比如 main-nav. 如果根據內容找不到合適的命名, 可以再結合表現來定, 比如 amount-choose, product-intro, main_nav,logo_box 名稱一律小寫, 多個單詞用下划線或者連字符連接, 比如 .time-countdown,size-choice,logo_box
- class 名稱中只能出現小寫的 26 個英文字母、數字、下划線和連字符(-), 任何其它字符都嚴禁出現.
- id的命名采用連接符命名法和下划線命名法,首字母小寫，如：buy-ok,shop_btn
- id 和 class 盡量用英文單詞命名.確實找不到合適的單詞時, 可以考慮使用產品的中文拼音。
- 對於中國特色詞匯可以使用拼音
- 除了產品名稱和特色詞匯, 其它任何情況下都嚴禁使用拼音.
* 在不影響語義的情況下, id 和 class 名稱中可以適當采用英文單詞縮寫, 比如 col, nav, hd, bd, ft 等, 但切忌自造縮寫.（常用縮寫總結在css規范部分） - id 和 class 名稱中的第一個詞必須是單詞全拼或語義非常清晰的單詞縮寫, 比如 goods, col.
基本規范
- 模塊命名要注意帶上模塊名，下面盡可能的簡寫，頁面級（app應用級）命名應該盡量簡潔;
- 盡可能地使用css-sprite
- 盡量通過class屬性定義樣式,將id留給hook
- 盡量不要在css中使用expression
- 組件開發中，可以先不考慮性能，盡量使用選擇符組以方便html調用，如.table-ctrl tbody tr td.selected{}；
- font中的字體用英文或unicode代替,如黑體可寫成SimHei：font: 12px/1.5 SimHei ,tahoma,arial,\5b8b\4f53,sans-serif;
CSS引用
- 統一以link形式引入
- 不推薦內嵌形式引入css
- 不推薦標簽出現在body中，特定頁面（比如404錯誤頁）除外。
- 不推薦內聯CSS，請盡量放在head標簽內
常用CSS屬性順序建議
- 顯示屬性(display, list-style, position, float, clear)
- 盒模型(width, height, margin, padding, border, background)
- 文本屬性(color, font, text-decoration, text-align, vertical-align, white-space, other text, content)
注釋風格
/*頭注釋*/ /*------------------------------------------------ @Filename: ve_goods @Description: 產品內頁 ------------------------------------------------*/ //商品屬性區塊 //產品顏色選擇 /*爆款*/ 5.Javascript規范
快速指引
- 必須使用 Tab 鍵進行代碼縮進，以節約代碼大小和提高可讀性。 (調整自己的編輯器tab制表符一律以4個空格來替代)
-
命名風格
|| || 規則 || 列如 ||
|| 類 || 混合式 || fixToTopClass ||
|| 公有方法 || 混合式 || isDate() check_password ||
|| 公有變量 || 混合式 || 列如 ||
|| 常量 || 大寫式 || 列如 ||* 其他建議風格
非必要
|| 結構 || 規則 || 列如 ||
|| 私有方法 || 混合式 || ||
|| 私有變量 || 混合式 || ||
|| 方法參數 || 混合式 || ||
|| 本地(local)變量 || 混合式 || || -
所有語句結束后，必須使用
;號結束
命名規范
基本原則：盡量避免潛在沖突；精簡短小, 見名知意。
- 局變量以$開頭，如$user，相當於：window.$user
- 常量全部大寫，單詞以下划線分隔，如STATIC_ROOT
- 普通變量，采用馱峰式寫法，首字母小寫，如userIcon，UserRelation
- 類名首字母大寫，如Object = function(){}
- 局部變量可縮寫，命名空間，類名盡量不縮寫
- 方法和函數，名字同普通變量名;
- 條件表達式、正則表式式，如果很復雜，給其命名
- 枚舉量, 同常量;
- 私有變量, 屬性和方法, 名字以下划線開頭,如_init(),_param;
- 保護變量, 屬性和方法, 名字同普通變量名;
注釋規范
因為基於gulp架構，jsDoc插件可以自動根據段落注釋自動生成可讀性很好的文檔，因此前端開發必須按照jsDoc的規范來寫了js注釋。