前端规范

    1. 规范说明

    此为前端开发团队遵循和约定的代码书写规范,意在提高代码的规范性和可维护性。
    此规范为参考规范,不全是硬性要求,部分硬性约定见下一条书写规范,统一团队编码规范和风格。让所有代码都是有规可循的,并且能够得到沉淀,减少重复劳动。

    1.1 结构说明

    项目结构
    —-|—- CSS文件结构
    —-|—- JS文件结构

    2. 书写规范

    2.1 样式与内容分离

    2.1.1 项目结构

    --- 
     |---- index.html             入口页    
     |---- js/                    JS //具体见JS细化结构                 
     |---- css/                   CSS //具体见CSS细化结构

    2.1.2 重构步骤约定

    1. index.html 全部样式附着于 class="xxx" 注: 此时文件中不包含任何一个 id=”xxx”
    2. 为上一步书写 CSS style
      [至此重构完成]
    3. 开始书写js交互文件,使用 IDClass 定位被操作句柄
    4. index.html 中需要的地方添加 id="xxx"data-xxx="xxx"
      [至此交互效果完成]

    2.1.3 命名规范

    • 文件及文件夹: 全部英文小写字母+数字或连接符”- , _ “,不可出现其他字符 如:../css/style.css, jquery.1.x.x.js
    • 文件:调用 /libs 文件需包含版本号,压缩文件需包含min关键词,其他插件则可不包含 如:/libs/jquery.1.9.1.js /libs/modernizr-1.7.min.js fileuploader.js plugins.js
    • ID: 匈牙利命名法 & 小駝峰式命名法
      如:firstName topBoxList footerCopyright
    • Class: [减号连接符]
      如:top-item main-box box-list-item-1
    • 尽量使用语义明确的单词命名,避免 left bottom 等方位性的词语

    2.1.4 格式&编码

    • 文本文件: .xxx UTF-8(无BOM) 编码
    • 图片文件: .png (PNG-24) .jpg (压缩率8-12)
    • 动态图片: .gif
    • 压缩文件: .tar.gz .zip

    2.2 CSS 细化规范

    2.2.1 CSS 文件结构

    --- ../css/
     |---- css/libs/reset.css                  CSS reset文件
     |----   
     |---- css/images/                          CSS-sprite 图片     
     |---- css/style.css                        CSS 样式表
     |----   
     |---- css/images/xxx/sprite.png           xxx  CSS-sprite 图片
     |---- css/xxx-style.css                   xxx  样式表

    2.2.2 CSS(含Less) 文件结构

    --- ../css/
     |---- css/libs/reset.less            CSS reset文件
     |---- css/libs/elements.less         Less 函数复用文件
     |----   
     |---- css/images/                          CSS-sprite 图片     
     |---- css/style.less                      主样式Less
     |---- css/style.css                       less -> css 自动生成
     |----   
     |---- css/images/xxx/sprite.png           xxx  CSS-sprite 图片
     |---- css/xxx-style.less                  xxx  Less
     |---- css/xxx-style.css                   less -> css 自动生成

    2.2.3 使用Less

    .less文件头部引入 reset.less & elements.less,之后调用如下属性传参即可,具体使用说明见 -> Lesselements 官方文档

    @import "libs/reset.less";  
    @import "libs/elements.less";
    
    .gradient
    .bw-gradient
    .bordered
    .drop-shadow
    .rounded
    .border-radius
    .opacity
    .transition-duration
    .rotation
    .scale
    .transition
    .inner-shadow
    .box-shadow
    .columns
    .translate

    2.2.4 CSS reset

    CSS reset 文件使用:reset.cssreset.less

    • reset文件用于重设各个浏览器的默认样式方案,解决其引起的耦合问题。
    • 也可使用 .clearfix 清除浮动

    2.2.5 CSS 注释格式约定

    /*
    @name: Drop Down Menu
    @description: Style of top bar drop down menu.
    @require: reset.css
    @author: Andy Huang(andyahung@geekpark.net)
    */

    其中,@require为可选项

    • CSS换行制表:使用 2 或4 个空格,而非[Tab]
    • 书写格式:
      • CSS名称+冒号+属性
        如:.box1 {float:left;}
      • 建议保留{左侧空格,字体名用\包含
        如:.box1,.box2,.box3 {font-family:Courier,'Courier New';}
      • 避免中文,或使用转义,推荐前者
        如:font-family: "Microsoft YaHei"; font-family:\5fae\8f6f\96c5\9ed1;

    2.2.6 CSS各属性的排列顺序:不做硬性要求

    如:以下2种顺序均可

    .box {
      /* 顺序1 */
      background: none repeat scroll 0 0 transparent;
      bottom: 11px;
      position: relative;
      width: 22px;
      z-index: 33;
    }
    .box {
      /* 顺序2 */
      z-index: 33;
      width: 22px;
      bottom: 11px;
      background: transparent none repeat scroll 0 0 ;
      position: relative;
    }

    2.2.7 CSS嵌套规则

    /* 推荐嵌套层级 */
    .ui-icon-rarr{}
    .ui-icon-larr{}
    .ui-title{}
    .ui-nav .ui-list{}
    .ui-table .ui-list{}
    
    /* 不推荐 */
    .ui-icon-rarr{}
    .ui-icon-larr{}
    .ui-title{}
    .ui-list{}
    .ui-nav{}

    2.2.8 CSS格式化

    勿格式化,保留下面这种格式,增加可读性和可维护性,后期后台程序(如:PHP/Python)会将CSS压缩成 一行 输出:

    .box{
      /* 勿格式化,增加可读性 */
      background: none repeat scroll 0 0 transparent;
      bottom: 11px;
      position: relative;
      width: 22px;
      z-index: 33;
    }

    2.3 XHTML 细化规范

    2.3.1 HTML 注释格式约定

    <!--
    @name: Drop Down Menu
    @description: Style of top bar drop down menu.
    @author: Andy Huang(andyahung@geekpark.net)
    -->
    
    <div id="header">
        <div class="xxx">
            <span>HTML行内注释格式</span>
        </div>
    </div><!-- #header end-->
    • HTML换行缩进:采用 2 空格

    2.3.2 HTML嵌套规则

    /* 推荐嵌套层级 */
      <ul class="ui-nav">
        <li class="ui-nav-item"> some text
          <ul class="ui-nav-item-child">
            <li> some text
              <ul class="ui-list">
                <li class="ui-list-item"> some text</li>
              </ul
            ...
           </ul>
        </li>
        <li
        ...
      </ul>

    2.3.4 * 第一行统一使用HTML5标准:

    <!DOCTYPE html>
    <html dir="ltr" lang="zh-CN">
    <head>
      <meta charset="utf-8" />
      <title>极客公园 | 创新者社区</title>
      <meta name="keywords" content="xxxx, xxx, xxxxx" />
      <meta name="description" content="xxxxxxxxxxxxxxxxxxxx" />

    2.3.5 Meta 的使用:(需要根据具体需求按需选择)可参看:cool-head

    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta http-equiv="Cache-Control" content="max-age=7200" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="alternate" type="application/rss+xml" title="RSS 2.0" href="http://feeds.geekpark.net/" />
    <link rel="shortcut icon" href="favicon.ico">
    <link rel="apple-touch-icon" href="/apple-touch-icon.png">
    
    <script type="text/javascript" src="/js/xxx.js"></script>
    <link rel="stylesheet" href="/css/xxx.css">
    
    <script type="text/javascript">
        //Google 统计代码 的位置在离</head>最近的位置
    </script>
    • <img>标签默认缺省格式:<img src="xxx.png" alt="缺省时文字" /> 避免出现src=”” 问题
    • <a>标签缺省格式:<a href="###" title="链接名称">xxx</> 注:target="_blank" 根据需求决定
    • <a>标签预留链接占位符使用###,参见:a标签占位符问题
    • 所有标签需要符合XHTML标准闭合
    • 一律统一标签结尾斜杠的书写形式:<br /> <hr /> 注意之间空格
    • 避免使用已过时标签,如:<b> <u> <i> 而用 <strong> <em>等代替
    • 使用data-xxx来添加自定义数据,如:<input data-xxx="yyy"/>
    • 避免使用style="xxx:xxx;"的内联样式表
    • 特殊符号使用参考HTML 符号实体

    2.4 JS 细化规范

    2.4.1 JS 文件结构

    ---/js/
    |---- /libs/plugin-1/       使用到的js插件1  
    |---- /libs/plugin-2/       使用到的js插件2  
    |---- /libs/plugin-3/       使用到的js插件3  
    |---- script.js             单独书写的js  
    |---- plugins.js            调用的plugins汇总  
    |---- juqery-1.9.x.min.js   调用jq库文件  
    • JS 换行缩进:采用 4 空格
    • 结束行需添加分号;
    • jQuery变量要求首字符为 $, 私有变量:首字符为_; 尽量避免全局变量.
    • 避免使用 eval(),setTimeOut使用调用函数,考虑重绘,回流 操作对页面影响 参看:reflows,repaints
    • JS调试使用console.log()console.dir()进行,避免使用弹出框,线上版需要注释所有调试代码
    • JS压缩混淆工具: JS Compressor 如果使用了压缩,需要留 name-src.js在同路径供今后修改使用
    2.4.2 jQuery Call
    <!-- Grab Google CDN jQuery. fall back to local if necessary -->  
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>  
    <script>!window.jQuery && document.write('<script src="js/jquery-1.7.2.min.js"><\/script>')</script>            
    2.4.3 jQuery Plugin
    2.4.4 JSON格式规范

    参考JSON Style Guide翻译,原版:Google JSON Style Guide

    HTML 细化规范

    • HTML head部分的结构参看:cool-head (摘取必要内容即可)
    • css 文件置于都 头部
    • jQueryGoogle Analytics引用置于 头部
    • 其他效果js统计代码 文件置于 尾部
    • HTML 代码尽量过一遍HTML5 验证
    • HTML 占位图片使用 temp.im & placehold.us 图片服务

    2.5 Responsive Web 规范

    从设计之处就坚持”Mobile First“的理念,在重构页面的时候要灵活采取响应式的解决方案。

    2.5.1 响应式实现途径

    * 设置 meta viewport 属性

    <meta name="viewport" content="width=device-width, initial-scale=1" />

    * 引入不同尺寸设备的样式表

    <link rel="stylesheet" type="text/css" href="style.css" media="screen, handheld" />
    <link rel="stylesheet" type="text/css" href="enhanced.css" media="screen  and (min-width: 40.5em)" />
    <!--[if (lt IE 9)&(!IEMobile)]>
    <link rel="stylesheet" type="text/css" href="enhanced.css" />
    <![endif]-->

    * 使用 CSS Media Queries 方法

    @media screen and (max-width: 40.5em) {
      .product-img {
        width: auto;
        float: none;
      }
    }
    @media screen and (max-width: 480px) {
    }

    * JS控制导航栏在 resize 事件 触发后的可见性,如:

    $(w).resize(function(){ //Update dimensions on resize
      sw = document.documentElement.clientWidth;
      sh = document.documentElement.clientHeight;
      checkMobile();
    });
    //Check if Mobile
    function checkMobile() {
      mobile = (sw > breakpoint) ? false : true;
      if (!mobile) { //If Not Mobile
        $('[role="tabpanel"],#nav,#search').show(); //Show full navigation and search
      } else { //Hide 
        if(!$('#nav-anchors a').hasClass('active')) {
          $('#nav,#search').hide(); //Hide full navigation and search
        }
      }
    }

    2.5.2 响应式解决方案

    * 弹性图片

    img {
      max-width: 100%;
      height: auto;
      width: auto\9; /* ie8 */
    }

    * 自适应嵌入媒体

    .video embed, .video object, .video iframe {
      width: 100%;
      height: auto;
    }

    * 禁用iPhone字体自适应功能:

    html {
      -webkit-text-size-adjust: none;
    }

    * 让 IE 9 以下的IE版本支持响应式:

    <!--[if lt IE 9]>
      <script src="http://css3-mediaqueries-js.googlecode.com/svn/trunk/css3-mediaqueries.js"></script>
    <![endif]-->

    2.6 Newletter 制作规范

    • CSS只可使用 内联样式表 ,如:style="margin:0;"
    • 设计之初遵循: 图上无文本,文本后无底纹 的规则
    • 使用 MailChimp HTML Email CSS Fix 参看下文链接
    • 引入 CSS Reset for HTML Email 参看下文链接
    • 使用Table布局而非DIV
    • 所有图片使用IMG标签,如:<img style="style="display:block" "src="" />
    • 可以适当使用占位符spacer.gif
    • 多用<br />换行而非<p>
    • 整体最佳宽度为:550-600px
    • 不使用Javascript
    • 正式发送给用户之前,多次测试

    更多细节参考下面链接:
    12 Killer Tips and Tricks for Building HTML Email
    Coding HTML Newsletters (EDM)