基於gulp的前端框架開發規範

時間 2019-11-11

原文原文鏈接

前端開發及相關規範 - 基於gulp的前端框架開發規範

1.前端開發工具的安裝和使用說明

前端開發工具的目錄結構

├── 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 是針對移動版javascript

安裝

前往 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 --php

升級自動化工具

進入前端自動化開發和部署工具的目錄，執行 npm install(使用國外鏡像) 或 cnpm install(使用國內鏡像)

執行自動化工具

如下操做，需進入 FeBuilder 的解壓目錄目錄下執行css

gulp
- 監控 less 文件變化，自動生成 css
- 監控 js/src 文件變化，自動在 dist 目錄生成對應的壓縮 js
- 監控 js/src 文件變化，自動在 doc 目錄，根據 jsdoc 格式，生成文檔
- 監控 css/sprite 目錄，若是有新 sns 文件，自動生成雪碧圖

注：若是添加新目錄，需從新執行該指令，不然新目錄不會監控html

gulp sprite 生成雪碧圖
gulp script 壓縮，合併，打包js
gulp 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最大的優勢。
前端

Javascripthtml5

爲了項目更容易管理和團隊協做，js的開發須要以模塊化的方式進行。
在 ve_2_1/js/src 目錄下創建按照功能模塊的不一樣，來創建文件夾及js文件java
- 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
*** 舉例：node

ve雙城首頁的js，咱們就創建在 js/src/web 目錄下，並命名爲index.js，它依賴於'jquery.slide', 'web/common', 'web/timer'和jquery，而'jquery.slide', 'web/common', 'web/timer'也依賴於jqeury，jquery已被全局化，那麼index.js應該是這樣的：jquery
- index.js:
javascript codeBuilder - v0.9
```
define('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應該是這樣的：web
- common.js:
javascript codeBuilder - v0.9
```
define('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>  
```

文檔的格式化 - 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>&nbsp;&gt;&nbsp;<a href="">名品特賣</a>&nbsp;&gt;&nbsp;<a href="">新安怡夏季大促</a>&nbsp;&gt;&nbsp;<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>

不推薦使用的元素

結構元素：無
頭部元素：無
列表元素：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)

註釋風格

css codeBuilder - v0.9

/*頭註釋*/ /*------------------------------------------------ @Filename: ve_goods @Description: 產品內頁 ------------------------------------------------*/ //商品屬性區塊 //產品顏色選擇 /*爆款*/

5.Javascript規範

快速指引

必須使用 Tab 鍵進行代碼縮進，以節約代碼大小和提升可讀性。 (調整本身的編輯器tab製表符一概以4個空格來替代)
命名風格
|| || 規則 || 列如 ||
|| 類 || 混合式 || fixToTopClass ||
|| 公有方法 || 混合式 || isDate() check_password ||
|| 公有變量 || 混合式 || 列如 ||
|| 常量 || 大寫式 || 列如 ||

*　其餘建議風格　非必要
　|| 結構 || 規則 || 列如 ||
　|| 私有方法 || 混合式 || ||
　|| 私有變量 || 混合式 || ||
　|| 方法參數 || 混合式 || ||
　|| 本地(local)變量 || 混合式 || ||
全部語句結束後，必須使用;號結束