[切换模式] 普通 [切换模式] MarkDown [切换模式] HTML You'll need to enable Javascript to use this tool. ### 1. 规范说明 此为礼物说前端开发团队遵循和约定的代码书写规范,意在提高代码的规范性和可维护性。 此规范为参考规范,不全是硬性要求。旨在统一团队编码规范和风格,让所有代码都是有规可循的,并且能够得到沉淀,减少重复劳动。 版本历史 2015.03.04 初次发布 2015.05.07 修改项目规范 ### 2. 项目规范 * 1)代码的松耦合,高度模块化,将页面内的元素视为一个个模块,相互独立,尽量避免耦合过高的代码,从html,css,js三个层面都要考虑模块化。 * 2)良好的注释。 * 3)注意代码的弹性,在性能和弹性的选择上,一般情况下以弹性为优先考虑条件,在保证弹性的基础上,适当优化性能。 * 4)严格按照规范编写代码。 #### 2.1 项目结构 --- |---- components //公共组件 |---- modules //模块 |---- pages //页面结构 |---- partial //inline html 碎片 |---- scripts //脚本文件 |---- style |---- fonts //字体 |---- img //图片 |---- css //样式表 |---- lib //无法模块化的组件 #### 2.2 命名规范 * 文件及文件夹: 全部英文小写字母+数字或连接符"`-` , `_` ",不可出现其他字符 如:`../css/style.css, jquery.1.x.x.js` * JS 压缩文件需包含`min`关键词 * JS 变量命名规范 // 类名:首字母大写,名词 ClassDefine // 方法名:使用动词,或动名词结合,驼峰 defineFunctionName // 变量名:与方法名类似,驼峰,对某些类型变量使用不同标识。 commonVariable // 普通变量 isBoolVariable // bool 类型变量,使用 is 开头 _privateVariable // 私有变量,使用 _ 开头 STATIC_VARIABLE // 常量,字母全部大写,中间使用 _ 分隔 * CSS * 为JavaScript预留钩子的命名, 尽量使用id属性,可以更快的获取到dom * 仅处理样式的选择器应做到“尽量无ID、无层级、无标签” * ID: [匈牙利命名法] & [小駝峰式命名法] 如:`firstName` `topBoxList` `footerCopyright` * Class: [减号连接符] 如:`top-item` `main-box` `box-list-item-1` * 图片使用 `模块-类别-功能` 的方法命名 #### 2.3 格式&编码 * 文本文件: `.xxx` UTF-8_\(无BOM\)_ 编码 * 图片文件: `.png` _(PNG-24)_ `.jpg` _(压缩率8-12)_ * 动态图片: `.gif` * 压缩文件: `.tar.gz` `.zip` ### 3 HTML 细化规范 #### 3.1 HTML 注释格式约定 HTML行内注释格式 #### 3.2 HTML嵌套规则 /* 推荐嵌套层级 */ some text some text some text #### 3.4 \* 第一行统一使用HTML5标准: 礼物说 - 礼物攻略精选 #### 3.5 Meta 的使用:(需要根据具体需求按需选择)可参看:[cool-head] * ``标签默认缺省格式:`` 避免出现[src="" 问题] * ``标签缺省格式:`xxx` 注:`target="_blank"` 根据需求决定 * ``标签预留链接占位符使用`###`,参见:[a标签占位符问题] * 所有标签需要符合XHTML标准闭合 * 一律统一标签结尾斜杠的书写形式:`` `` 注意之间空格 * 避免使用已过时标签,如:`` `` `` 而用 `` ``等代替 * 使用`data-xxx`来添加自定义数据,如:`` * 避免使用`style="xxx:xxx;"`的内联样式表 * 特殊符号使用参考[HTML 符号实体] #### 3.6 其他 * HTML `head`部分的结构参看:[cool-head] \(摘取必要内容即可) * `css` 文件置于都 **头部** * `jQuery` 及 `Google Analytics`引用置于 **头部** * 其他效果`js`及`统计代码` 文件置于 **尾部** * HTML 代码尽量过一遍[HTML5 验证] * HTML 占位图片使用 [temp.im] & [placehold.us] 图片服务 ### 4 CSS 细化规范 #### 4.1 CSS 文件结构 --- ../css/ |---- com //公共库 |---- components //通用控件样式库 |---- reset.scss //重置浏览器样式 |---- minxins.scss //Sass minxin 库 |---- lws.scss //包含通用控件、重置文件以及 minxin 库,所有页面统一引用该文件 |---- app //app webview 样式 |---- mobile //移动样式 |---- … … |---- module1 //各模块样式表 |---- module2 //各模块样式表 |---- … … #### 4.2 CSS 注释格式约定 /* @name: Drop Down Menu @description: Style of top bar drop down menu. @require: reset.css @author: Rain 15-03-04 */ _其中,@require为可选项_ #### 4.3 CSS的属性重要性按顺序排序如下有: * 显示与浮动(Diplay&Flow) * 定位(Positioning) * 尺寸(Dimensions) * 边相关属性(Margins、Padding、Borders、Outline) * 字体样式(Typographic Styles) * 背景(Backgrounds) * 其它样式(Opacity、Cursors、Generated Content) 在实践中可以归纳为定位、布局、内部样式三部分,推荐写法如下: .box { display: block; position: absolute; left: 0px; z-index: 33; width: 22px; height: 11px; padding: 0px; color: red; font-size: 18px; background: transparent none repeat scroll 0 0 ; } ### 5 JS 细化规范 #### 5.1 JS 文件结构 ---/js/ |---- /module/xx.js //模块内 js |---- app //app webview |---- mobile //移动端 |---- components //项目内组件 |---- util //基础方法 |---- app.js //通用 js 设置 所有页面都需要加载 * JS 换行缩进:采用 4 空格 * 结束行需添加分号`;` * JS调试使用`console.log()`及`console.dir()`进行,避免使用弹出框,线上版需要注释所有调试代码 #### 5.2 书写规范 1、每行代码长度 每行长度最长 100 字符,若对长度没概念,可设定编辑器屏幕显示区域来达到控制目的。 2、空格使用 1)一元操作符前后没有空格,for example: i++; i--; 2)二元操作符前后使用一个空格,for example: var myName = 'beile'; 3、方法定义 1)括号前不留空格,')' 后使用一个空格,并紧跟 '{',多个参数使用 ', ' 隔开,for example: function getValue(firstParam, secondParam) { // do something ... } 4、条件控制 1)难以描述,请注意空格使用,for example: // if 语句 if (condition) { // do something... } else if (condition) { // do another thing... } else { // do something... } // for 语句 for (var i = 0; i < 10; i++) { // do something... } // while 语句 while (condition) { // do something... } // switch 语句 stitch (condition) { case 'case1': // do something... case 'case2': // do something... default: // do something... } #### 5.3 大字符串的创建方式 不推荐使用 '+' 来拼接大字符串,for example: var listHtml = '' + 'first item' + 'second item' + ''; 通过使用数组来创建大字符串是更好的方式,for example: var listHtml = [ '', 'first item', 'second item', '' ].join(''); // 使用 jion 拼接 #### 5.4 注释 1、文件头部注释: 包含版权信息或开源协议等,不做强制要求。for example: // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // 2、自定义 Class 注释:(可以使用多个 * 将注释包裹)for example: /************************************************ * * 类的功能介绍,简述类的使用方法和功能。 * @require: a.js * b.js // 依赖的 js 文件 * @author: 作者 * @create: 创建时间 * @modify: 最后修改时间,对于通用组件不做强制要求。但是对于业务代码,每次修改需写明负责人和时间。 * ************************************************* 3、方法的注释 for example: /** * 方法的功能介绍 * @param: {string} str * {object} options // 指明参数的类型 * @return: {string} str // 返回类型 * @author: 作者 * @create: 创建时间 * @modify: 最后修改时间 */ 4、分区的注释 for example: // =============================================================== // 这是一个主分区 // =============================================================== 5、子分区的注释 for example: // 这是一个子分区 // =============================================================== #### 5.5 jQuery Plugin * IE对HTML5标签支持,以及浏览器特性检测:[Modernizr] & [html5shiv] * 定制&统一 浏览器的滚动条样式:[jquery-scroll] & [Lionbars] * hover提示效果文字:[bootstrap-tooltips] & [tipsy] * 滚动条跟随nav效果:[bootstrap-scrollspy] * 提示冒泡文字:[grumble.js] * 导航栏过渡效果:[lavalamp] * 移动设备的滚动效果:[iscroll 4] * Mac OS Lion 风格的滚动条:[Lionbars] * 弹性SlideShow:[kwicks for jQuery] * 瀑布流:[isotope] * 抖动效果:[jQ shake] * LightBox:[fancyBox] * KenDo UI:[KenDo UI] * textarea自适应高度:[elastic] * 提示区域 & 提示层:[noty] * 浮动话题泡:[jQuery grumble] * 旋转进度:[jQuery Knob] #### 5.6 JSON格式规范 * 所有的属性名必须在双引号内。字符类型的属性值必须使用双引号,其它类型值(如布尔或数字)不应该使用双引号。 * 以结构层次组织数据 详细参考[JSON Style Guide翻译],原版:[Google JSON Style Guide] ### 6 Responsive Web 规范 从设计之处就坚持"[Mobile First]"的理念,在重构页面的时候要灵活采取响应式的解决方案。 #### 6.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 } } } #### 6.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版本支持响应式: ### 7 开发流程 #### 7.1 分工安排 * 1)分工原则为公共组件(包括common.css和public.JS)一人维护,各栏目其他人负责,每个栏目正常情况下一人负责,要详细写明注释,如果多人合作,维护的人员注意添加注释信息,具体注释细则,详见注释规则; * 2)VD设计完设计图后,先和交互设计师沟通,确定设计可行,然后先将设计图给公共组件维护者,看设计图是否需要提取公共组件,然后再提交给相应栏目的WD。如果有公共组件要提取,公共组件维护者需对栏目WD说明。 * 3)如果确定没有公共组件需提取,交互设计师直接和各栏目的WD交流,对照着VD的设计图进行说明,WD完成需求; * 4)WD在制作页面的时候,需先去common文件中查询是否已经存在设计图中的组件,如果有,直接调用;没有,则在app.css和app.JS中添加相应的代码。 * 5)WD在制作过程中,发现有高度重用的模块,却未被加入到公共组件中,需向公共组件维护人进行说明,然后工作组件维护人决定是否添加该组件。如果确定添加,则向WD们说明添加了新组件,让WD们检查之前是否添加了类似组件,统一更新成新组件的用法,删除之前自定义的css和js。虽然麻烦,但始终把可维护性放在首位。 * 6)公共组件维护者的公共组件说明文档,需图片和说明文字配套,方便阅读。 ### 8 资源汇总 #### 8.1 for Mac OS *for more app detial check -> [IUSETHIS](http://osx.iusethis.com/user/hzlzh 'App pack') //Todo* #### 8.2 前端相关工具 * 编辑器:[WebStorm] / [Sublime Text 2] * 命令行:[iTerm2] * 浏览器调试环境:[Chrome] / [Firefox] + [Firebug] * 移动设备调试环境:[Mozilla Fennec] * 兼容性测试:[Parallels Desktop] + Win XP(IE 8) * 版本控制工具:[GitHub for Mac] / [SourceTree] * FTP工具:[Filezilla] / [ForkLift] * HTTP抓包及Post/Get模拟:[Charles] * PHP集成环境:[XAMPP for Mac] / [MAMP] * SQL数据库管理:[Sequel Pro] * 标注工具:[Mark Man] / [xScope] * 取色拾色器: [Frank DeLoupe] / [Sip] / [Snip] / [xScope] * MarkDown编辑器:[Mou] * 浏览器免刷新开发环境:[LiveReLoad] / [CodeKit] * CSS Sprite切图工具:[SpriteRight] * Less -> CSS 编译:[CodeKit] / [LiveReLoad] / [Less] * 配色方案工具:[ColorSchemer Studio] * 多浏览器Cookie管理:[Cookie] * 图片素材收集:[Sparkbox] / [Pixa] #### 8.3 其他效率工具 * 快速启动及切换app:[Alfred] * 剪切板历史记录:[Alfred]*(Fretures -> Clipboard)* * 笔记:[Evernote] * 轻量级GTD:[Clear] * 压缩解压:[The Unarchiver] / [Keka] / [iPack] * 语言文档和快捷词扩展:[Dash] * 时间中断提醒:[BreakTime] #### 8.4 其他收集 * Firefox 扩展收藏集 -> [Firefox Add-ons collections] * Chrome 扩展 -> 待添加 * Sublime Text 2 技巧 -> [ST2 资源技巧汇总] #### 8.5 相关技巧 * [各浏览器的缓存清除方法] * [测试技巧Gmail 添加词缀 .+ 获得多个邮件的方法] * [关于Mac Win Linux跨系统传文件,文件名乱码的解决方案] * [技术团队"路由代理"解决方案和使用须知] ### 9 参考数据 * [国内 PC 浏览器分布情况] * [国内 Mobile 浏览器分布情况] ### 持续更新 [reflows,repaints]: http://www.zhangxinxu.com/wordpress/2010/01/%E5%9B%9E%E6%B5%81%E4%B8%8E%E9%87%8D%E7%BB%98%EF%BC%9Acss%E6%80%A7%E8%83%BD%E8%AE%A9javascript%E5%8F%98%E6%85%A2%EF%BC%9F/ "重绘,回流参考" [src="" 问题]: http://js8.in/555.html "src="" 问题" [a标签占位符问题]: http://www.v2ex.com/t/48511/ "a标签占位符问题" [匈牙利命名法]: http://zh.wikipedia.org/wiki/%E5%8C%88%E7%89%99%E5%88%A9%E5%91%BD%E5%90%8D%E6%B3%95 "Wiki:匈牙利命名法" [小駝峰式命名法]:http://zh.wikipedia.org/wiki/%E9%A7%9D%E5%B3%B0%E5%BC%8F%E5%A4%A7%E5%B0%8F%E5%AF%AB "小駝峰式命名法" [CSS Compressor]: http://www.csscompressor.com/ "CSS 压缩" [JS Compressor]: http://javascriptcompressor.com/ "JS 压缩和混淆" [HTML 符号实体]: http://www.w3school.com.cn/html/html_entities.asp [Google JSON Style Guide]:http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml [JSON Style Guide翻译]:https://github.com/darcyliu/google-styleguide/blob/master/JSONStyleGuide.md [meta viewport]: https://developer.mozilla.org/en-US/docs/Mobile/Viewport_meta_tag " ViewPort" [CSS Media Queries]: http://css-tricks.com/css-media-queries/ [resize 事件]: http://api.jquery.com/resize/ [Lesselements]: http://lesselements.com/ [Bootstrap]: http://twitter.github.com/bootstrap/ "Bootstrap, from Twitter" [reset.css]: https://github.com/hzlzh/cool-head/blob/master/Template/css/libs/reset.css "CSS reset 文件" [reset.less]: https://github.com/hzlzh/cool-head/blob/master/Template/css/libs/reset.less "reset.less from HTML5 Boilerplate" [elements.less]: https://github.com/hzlzh/cool-head/blob/master/Template/css/libs/elements.less "elements.less from lesselements" [HTML5 验证]: http://html5.validator.nu/ [Modernizr]: http://modernizr.com/download/ [DD_belatedPNG]: http://www.dillerdesign.com/experiment/DD_belatedPNG/ [html5shiv]: https://github.com/aFarkas/html5shiv [jquery-scroll]: https://github.com/thomd/jquery-scroll/ [Lionbars]: https://github.com/Charuru/lionbars [bootstrap-tooltips]: http://twitter.github.com/bootstrap/javascript.html#tooltips [bootstrap-scrollspy]: http://twitter.github.com/bootstrap/javascript.html#scrollspy [grumble.js]: https://github.com/jamescryer/grumble.js [lavalamp]: http://www.gmarwaha.com/blog/2007/08/23/lavalamp-for-jquery-lovers/ [iscroll 4]: https://github.com/cubiq/iscroll [kwicks for jQuery]: https://github.com/Mottie/Kwicks [isotope]: https://github.com/desandro/isotope [jQ shake]: https://gist.github.com/3270711 [fancyBox]: https://github.com/fancyapps/fancyBox [KenDo UI]: http://www.kendoui.com/purchase.aspx [elastic]: http://unwrongest.com/projects/elastic/ [cool-head]: https://github.com/hzlzh/cool-head [noty]: https://github.com/needim/noty [jQuery grumble]: https://github.com/jamescryer/grumble.js [tipsy]: https://github.com/jaz303/tipsy [jQuery Knob]: https://github.com/aterrien/jQuery-Knob [各浏览器的缓存清除方法]: https://github.com/GeekPark/Doc/wiki/%5B%E5%A6%82%E4%BD%95%E9%81%BF%E5%85%8D%E7%BC%93%E5%AD%98%5D%E5%90%84%E6%B5%8F%E8%A7%88%E5%99%A8%E6%B5%8B%E8%AF%95%E7%BD%91%E9%A1%B5%E6%97%B6%E6%B8%85%E9%99%A4%E7%BC%93%E5%AD%98%E7%9A%84%E6%96%B9%E6%B3%95 [测试技巧Gmail 添加词缀 .+ 获得多个邮件的方法]: https://github.com/GeekPark/Doc/wiki/%5B%E6%B5%8B%E8%AF%95%E6%8A%80%E5%B7%A7%5DGmail-%E6%B7%BB%E5%8A%A0%E8%AF%8D%E7%BC%80(.--)%E8%8E%B7%E5%BE%97%E5%A4%9A%E4%B8%AA%E9%82%AE%E4%BB%B6%E7%9A%84%E6%96%B9%E6%B3%95 [关于Mac Win Linux跨系统传文件,文件名乱码的解决方案]: https://github.com/GeekPark/Doc/wiki/%E5%85%B3%E4%BA%8E%5BMac%5D-%5BWin%5D-%5BLinux%5D%E8%B7%A8%E7%B3%BB%E7%BB%9F%E4%BC%A0%E6%96%87%E4%BB%B6%EF%BC%8C%E6%96%87%E4%BB%B6%E5%90%8D%E4%B9%B1%E7%A0%81%E7%9A%84%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88 [技术团队"路由代理"解决方案和使用须知]: https://github.com/GeekPark/Doc/wiki/%E6%8A%80%E6%9C%AF%E5%9B%A2%E9%98%9F%5B%E8%B7%AF%E7%94%B1%E4%BB%A3%E7%90%86%5D%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88%E5%92%8C%E4%BD%BF%E7%94%A8%E9%A1%BB%E7%9F%A5 [Mobile First]: http://www.lukew.com/ff/entry.asp?933 "Mobile First" [WebStorm]:https://www.jetbrains.com/webstorm/ [Sublime Text 2]:http://www.sublimetext.com/2 [TextMate 2]:https://github.com/textmate/textmate [Intellij IDEA]:http://www.jetbrains.com/idea/ [Vim]:http://macvim.org/ [Chrome]:http://www.google.com/chrome [Firefox]:http://www.mozilla.org/ [Firebug]:http://getfirebug.com/ [Parallels Desktop]:http://www.parallels.com/cn/products/desktop/ [Versions]:http://versionsapp.com/ [GitHub for Mac]:http://mac.github.com/ [SourceTree]:http://www.sourcetreeapp.com/ [Filezilla]:http://filezilla-project.org/ [ForkLift]:http://itunes.apple.com/us/app/forklift/id412448059?mt=12 [Charles]:http://www.charlesproxy.com/ [XAMPP for Mac]:http://www.apachefriends.org/en/xampp-macosx.html [MAMP]:http://http://mamp.info/ [Mark Man]:http://www.getmarkman.com/ [xScope]:http://itunes.apple.com/us/app/xscope/id447661441?mt=12 [Sip]:http://itunes.apple.com/app/sip/id507257563?mt=12 [Snip]:http://itunes.apple.com/us/app/snip/id512505421?mt=12 [Mou]:http://mouapp.com/ [LiveReLoad]:http://http://livereload.com/ [Cookie]:http://itunes.apple.com/us/app/cookie/id415585910?mt=12 [ColorSchemer Studio]:http://itunes.apple.com/us/app/colorschemer-studio/id417896628?mt=12 [Less]:http://incident57.com/less/ [CodeKit]: http://incident57.com/codekit/ [SpriteRight]:http://itunes.apple.com/us/app/spriteright/id488584662?mt=12 [iTerm2]: http://www.iterm2.com/ [Mozilla Fennec]: http://www.mozilla.org/projects/fennec [Sequel Pro]: http://www.sequelpro.com/ [Sparkbox]: http://seesparkbox.com/ [Pixa]: http://www.pixa-app.com/ [Alfred]: http://www.alfredapp.com/ [Evernote]: http://www.evernote.com/ [The Unarchiver]: https://itunes.apple.com/hk/app/the-unarchiver/id425424353?mt=12 [Keka]: https://itunes.apple.com/us/app/keka/id470158793?mt=12 [iPack]: https://itunes.apple.com/us/app/ipack/id433386677?mt=12 [Frank DeLoupe]: http://www.jumpzero.com/frank/ [Dash]: http://kapeli.com/ [BreakTime]: http://itunes.apple.com/cn/app/breaktime/id427475982?mt=12 [Clear]: http://itunes.apple.com/cn/app/breaktime/id427475982?mt=12 [Chrome Remote USB Debugging]: https://developers.google.com/chrome/mobile/docs/debugging [Fiddler2]: http://www.fiddler2.com/fiddler2/ [Subversion]: http://subversion.apache.org/ [Putty]: http://www.putty.org/ [MarkdownPad]: http://markdownpad.com/ [F5]: http://www.getf5.com/ [less.org]: http://lesscss.org/ [haml.info]: http://haml.info/ [Github for Windows]: http://windows.github.com/ [Firefox Responsive Design View]: https://developer.mozilla.org/en-US/docs/Tools/Responsive_Design_View/ [7z]: http://www.7-zip.org/ [temp.im]: http://temp.im/ "Placehold image" [placehold.us]: http://placehold.us/ [Firefox Add-ons collections]: https://addons.mozilla.org/en-US/firefox/collections/hzlzh/hzlzh/ [ST2 资源技巧汇总]: http://www.douban.com/group/topic/28027863/ [Wiki page index]: https://github.com/GeekPark/Doc/wiki/_pages [12 Killer Tips and Tricks for Building HTML Email]: http://www.queness.com/post/8784/12-killer-tips-and-tricks-for-building-html-email [Coding HTML Newsletters (EDM)]: http://www.web-ed.com.au/2011/05/coding-html-newsletters-edms-quick-guide/ [MIT License]: http://en.wikipedia.org/wiki/MIT_License [国内 PC 浏览器分布情况]: http://tongji.baidu.cn/data/browser [国内 Mobile 浏览器分布情况]: http://tongji.baidu.cn/data/mobile/brand