基于gulp的前端框架开发规范

前端开发及相关规范 - 基于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 是针对移动版

安装

前往 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 压缩，合并，打包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最大的优点。

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:
javascriptcodeBuilder - 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应该是这样的：
- common.js:
javascriptcodeBuilder - 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的方法
htmlcodeBuilder - 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项，提高兼容性

htmlcodeBuilder - 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，结束时则加斜杠 /(表示标签闭合了)。

htmlcodeBuilder - 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模板 -- 仅供参考

htmlcodeBuilder - 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,5b8b4f53,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)

注释风格

csscodeBuilder - v0.9

    /*头注释*/
    /*------------------------------------------------
    @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注释。

基于gulp的前端框架开发规范

前端开发及相关规范 - 基于gulp的前端框架开发规范

1.前端开发工具的安装和使用说明

前端开发工具的目录结构

statics/Lib // 第三方JS包 目录说明

安装

升级自动化工具

执行自动化工具

数据格式约定

2.前端开发工具的相关约定

文件和目录的命名约定

开发文件的建立

什么是CSS Sprites？？

文档的格式化 - tab制表符来控制缩进

3.HTML静态模板规范

约定

页头声明

HTML注释

css ， js 文件，在页面上的位置

标准前端html模板 -- 仅供参考

推荐使用的元素

不推荐使用的元素

转世重生的元素

4.CSS规范

文件编码约定

id 和 class 命名约定

基本规范

CSS引用

常用CSS属性顺序建议

注释风格

5.Javascript规范

快速指引

命名规范

注释规范

statics/Lib // 第三方JS包目录说明