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

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

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

前端开发工具的目录结构

htmlcodeBuilder - 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 压缩，合并，打包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>
      <!-- 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项，提高兼容性

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>

推荐使用的元素

• 结构元素：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,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注释。