前端规范

转自《Front End Standards》

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交互文件，使用 ID 和 Class 定位被操作句柄
  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.css 或 reset.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 注释格式约定

  • HTML换行缩进：采用 2 空格

2.3.2 HTML嵌套规则

/* 推荐嵌套层级 */

  • some text
    • some text
      • some text

    • 2.3.4 * 第一行统一使用HTML5标准：

      极客公园 | 创新者社区 #### 2.3.5 Meta 的使用：（需要根据具体需求按需选择）可参看：[cool-head] </head>
      • <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
      2.4.3 jQuery Plugin
      2.4.4 JSON格式规范

      参考JSON Style Guide翻译，原版：Google JSON Style Guide

      HTML 细化规范

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

      2.5 Responsive Web 规范

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

      2.5.1 响应式实现途径

      * 设置 meta viewport 属性

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

      * 使用 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版本支持响应式：

      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)

      2.7 生产力工具推荐

      2.7.1 for Mac OS

      for more app detial check -> IUSETHIS

      2.7.1.1 前端相关工具(Mac)
      2.7.1.2 其他效率工具
      2.7.2.1 前端相关工具(Windows)
      2.7.2.2 其他效率工具(Windows)

      2.7.3 其他收集

      2.8 相关技巧

      Wiki page index

      2.9 参考数据

      涉及到 设计->重构->兼容性->测试 时可参考各浏览器的占用情况
      -- updated: 2013/02 - 2013/04 via Google Analytics of GeekPark

      总浏览器分布 IE版本分布 移动设备分布 屏幕解决方案
      类别 占有率
      Chrome 40.39%
      Internet Explorer 24.86%
      Safari & Safari (in-app) 16.05%
      Android Browser 10.57%
      Firefox 5.99%
      Opera 0.69%
      Opera Mini 0.37%
      Mozilla Compatible Agent 0.14%
      Maxthon 0.13%
      版本号 占有率
      IE 8 60.97%
      IE 9 17.11%
      IE 7 8.39%
      IE 6 7.63%
      IE 10 5.87%
      IE 4 0.02%
      移动平台 占有率
      iOS 50.39%
      Android 48.05%
      Windows Phone 0.96%
      Nokia 0.33%
      PC & Mac屏幕分辨率 占有率
      1366x768 21.55%
      1440x900 12.70%
      1280x800 9.60%
      1280x1024 6.68%
      320x480 6.38%
      1920x1080 6.27%

      使用团队

      此规范基于 MIT License 开源，持续更新维护中，可 Star 或 Fork 本项来形成你的规范，请以 创建[issues] 的方式反馈，或发起Pull Request

      [src="" 问题]: http://js8.in/555.html "src="" 问题"
      [a标签占位符问题]: http://www.v2ex.com/t/48511/ "a标签占位符问题"

posted @ 2016-01-06 17:22  Phoenix.C  阅读(209)  评论(0)    收藏  举报