前端开发规范手册

此手册主要实现的目标:代码一致性和最佳实践。通过代码风格的一致性,降低维护代码的成本以及改善多人协作的效率。同时遵守最佳实践,确保页面性能得到最佳优化和高效的代码。此手册是在开发中积累下来的经验和参考其它规范/指南制定的,它只是起指导作用,除个别条目强制之外,大多数为非强制约束,开发者可根据自己的实际情况自行决定是否要遵守该指南只是保证大方向一致性和最佳实践的阶段性总结,不是最后结论,它会随着时间而变化
展开查看详情

1. 目 录 致谢 介紹 基本原则 HTML 通用约定 语义化 HEAD CSS 通用约定 字体排印 模块组织 Less 规范 性能优化 JavaScript 通用约定 jQuery 规范 性能优化 移动端优化 工具箱 参考 本文档使用 书栈(BookStack.CN) 构建 - 1 -

2.致谢 致谢 当前文档 《前端开发规范手册》 由 进击的皇虫 使用 书栈 (BookStack.CN) 进行构建,生成于 2018-03-19。 书栈(BookStack.CN) 仅提供文档编写、整理、归类等功能,以 及对文档内容的生成和导出工具。 文档内容由网友们编写和整理,书栈(BookStack.CN) 难以确认 文档内容知识点是否错漏。如果您在阅读文档获取知识的时候,发现文 档内容有不恰当的地方,请向我们反馈,让我们共同携手,将知识准 确、高效且有效地传递给每一个人。 同时,如果您在日常生活、工作和学习中遇到有价值有营养的知识 文档,欢迎分享到 书栈(BookStack.CN) ,为知识的传承献上您的 一份力量! 如果当前文档生成时间太久,请到 书栈(BookStack.CN) 获取 最新的文档,以跟上知识更新换代的步伐。 文档地址:http://www.bookstack.cn/books/Aaaaaashu- Guide 书栈官网:http://www.bookstack.cn 书栈开源:https://github.com/TruthHun 分享,让知识传承更久远! 感谢知识的创造者,感谢知识的分享 者,也感谢每一位阅读到此处的读者,因为我们都将成为知识的传承 者。 本文档使用 书栈(BookStack.CN) 构建 - 2 -

3.致谢 本文档使用 书栈(BookStack.CN) 构建 - 3 -

4.介紹 介紹 前端开发规范手册 Github: 仓库地址 知笔墨: 手册地址 前端开发规范手册 Github: 仓库地址 知笔墨:手册地址 此手册主要实现的目标:代码一致性和最佳实践。通过代码风格的一致 性,降低维护代码的成本以及改善多人协作的效率。同时遵守最佳实 践,确保页面性能得到最佳优化和高效的代码。 此手册是在开发中积累下来的经验和参考其它规范/指南制定的,它只 是起指导作用,除个别条目强制之外,大多数为非强制约束,开发者可 根据自己的实际情况自行决定是否要遵守 该指南只是保证大方向一致性和最佳实践的阶段性总结,不是最后结 论,它会随着时间而变化。 本文档使用 书栈(BookStack.CN) 构建 - 4 -

5.介紹 本文档使用 书栈(BookStack.CN) 构建 - 5 -

6.介紹 本文档使用 书栈(BookStack.CN) 构建 - 6 -

7.基本原则 基本原则 基本原则 结构、样式、行为分离 缩进 文件编码 一律使用小写字母 省略外链资源 URL 协议部分 统一注释 HTML 注释 CSS 注释 JavaScript 注释 代码验证 基本原则 结构、样式、行为分离 尽量确保文档和模板只包含 HTML 结构,样式都放到样式表里,行为 都放到脚本里。 缩进 统一两个空格缩进(总之缩进统一即可),不要使用 Tab 或者 Tab 、空格混搭。 文件编码 使用不带 BOM 的 UTF-8 编码。 在 HTML中指定编码 <meta charset="utf-8"> ; 本文档使用 书栈(BookStack.CN) 构建 - 7 -

8.基本原则 无需使用 @charset 指定样式表的编码,它默认为 UTF-8 (参 考 @charset"">@charset); 一律使用小写字母 1. <!-- Recommended --> 2. <img src="google.png" alt="Google"> 3. 4. <!-- Not recommended --> 5. <A HREF="/">Home</A> 1. /* Recommended */ 2. color: #e5e5e5; 3. 4. /* Not recommended */ 5. color: #E5E5E5; 省略外链资源 URL 协议部分 省略外链资源(图片及其它媒体资源)URL 中的 http / https 协议,使 URL 成为相对地址,避免 Mixed Content 问题,减小文 件字节数。 其它协议( ftp 等)的 URL 不省略。 1. <!-- Recommended --> 2. <script src="//www.google.com/js/gweb/analytics/autotrack.js"> </script> 3. 4. <!-- Not recommended --> 5. <script src="http://www.google.com/js/gweb/analytics/autotrack.js"> </script> 1. /* Recommended */ 2. .example { 本文档使用 书栈(BookStack.CN) 构建 - 8 -

9.基本原则 3. background: url(//www.google.com/images/example); 4. } 5. 6. /* Not recommended */ 7. .example { 8. background: url(http://www.google.com/images/example); 9. } 统一注释 通过配置编辑器,可以提供快捷键来输出一致认可的注释模式。 HTML 注释 模块注释 1. <!-- 文章列表列表模块 --> 2. <div class="article-list"> 3. ... 4. </div> 区块注释 1. <!-- 2. @name: Drop Down Menu 3. @description: Style of top bar drop down menu. 4. @author: Ashu(Aaaaaashu@gmail.com) 5. --> CSS 注释 组件块和子组件块以及声明块之间使用一空行分隔,子组件块之间三空 行分隔; 1. /* ========================================================================== 2. 组件块 本文档使用 书栈(BookStack.CN) 构建 - 9 -

10.基本原则 3. ============================================================================ */ 4. 5. /* 子组件块 6. ============================================================================ */ 7. .selector { 8. padding: 15px; 9. margin-bottom: 15px; 10. } 11. 12. 13. 14. /* 子组件块 15. ============================================================================ */ 16. .selector-secondary { 17. display: block; /* 注释*/ 18. } 19. 20. .selector-three { 21. display: span; 22. } JavaScript 注释 单行注释 必须独占一行。 // 后跟一个空格,缩进与下一行被注释说明的代码 一致。 多行注释 避免使用 /*...*/ 这样的多行注释。有多行注释内容时,使用多个 本文档使用 书栈(BookStack.CN) 构建 - 10 -

11.基本原则 单行注释。 函数/方法注释 1. 函数/方法注释必须包含函数说明,有参数和返回值时必须使用注 释标识。; 2. 参数和返回值注释必须包含类型信息和说明; 3. 当函数是内部函数,外部不可访问时,可以使用 @inner 标识; 1. /** 2. * 函数描述 3. * 4. * @param {string} p1 参数1的说明 5. * @param {string} p2 参数2的说明,比较长 6. * 那就换行了. 7. * @param {number=} p3 参数3的说明(可选) 8. * @return {Object} 返回值描述 9. */ 10. function foo(p1, p2, p3) { 11. var p3 = p3 || 10; 12. return { 13. p1: p1, 14. p2: p2, 15. p3: p3 16. }; 17. } 文件注释 文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。 应该提供文件的大体内容, 它的作者, 依赖关系和兼容性信息。如下: 1. /** 2. * @fileoverview Description of file, its uses and information 3. * about its dependencies. 4. * @author user@meizu.com (Firstname Lastname) 本文档使用 书栈(BookStack.CN) 构建 - 11 -

12.基本原则 5. * Copyright 2015 Meizu Inc. All Rights Reserved. 6. */ 代码验证 使用 W3C HTML Validator 来验证你的HTML代码有效性; 使用 W3C CSS Validator 来验证你的CSS代码有效性; 代码验证不是最终目的,真的目的在于让开发者在经过多次的这种验证 过程后,能够深刻理解到怎样的语法或写法是非标准和不推荐的,即使 在某些场景下被迫要使用非标准写法,也可以做到心中有数。 本文档使用 书栈(BookStack.CN) 构建 - 12 -

13.HTML HTML HTML HTML 尽量遵循 HTML 标准和语义,但是不要以牺牲实用性为代价。任何时 候都要尽量使用最少的标签并保持最小的复杂度。 本文档使用 书栈(BookStack.CN) 构建 - 13 -

14.通用约定 通用约定 通用约定 标签 Class 与 ID 属性顺序 引号 嵌套 布尔值属性 通用约定 标签 自闭合(self-closing)标签,无需闭合 ( 例如: img input br hr 等 ); 可选的闭合标签(closing tag),需闭合 ( 例如: </li> 或 </body> ); 尽量减少标签数量; 1. <img src="images/google.png" alt="Google"> 2. <input type="text" name="title"> 3. 4. <ul> 5. <li>Style</li> 6. <li>Guide</li> 7. </ul> 8. 9. <!-- Not recommended --> 10. <span class="avatar"> 11. <img src="..."> 12. </span> 本文档使用 书栈(BookStack.CN) 构建 - 14 -

15.通用约定 13. 14. <!-- Recommended --> 15. <img class="avatar" src="..."> Class 与 ID class 应以功能或内容命名,不以表现形式命名; class 与 id 单词字母小写,多个单词组成时,采用中划 线 - 分隔; 使用唯一的 id 作为 Javascript hook, 同时避免创建无样式 信息的 class; 1. <!-- Not recommended --> 2. <div class="j-hook left contentWrapper"></div> 3. 4. <!-- Recommended --> 5. <div id="j-hook" class="sidebar content-wrapper"></div> 属性顺序 HTML 属性应该按照特定的顺序出现以保证易读性。 id class name data-xxx src, for, type, href title, alt aria-xxx, role 1. <a id="..." class="..." data-modal="toggle" href="###"></a> 2. 3. <input class="form-control" type="text"> 本文档使用 书栈(BookStack.CN) 构建 - 15 -

16.通用约定 4. 5. <img src="..." alt="..."> 引号 属性的定义,统一使用双引号。 1. <!-- Not recommended --> 2. <span id='j-hook' class=text>Google</span> 3. 4. <!-- Recommended --> 5. <span id="j-hook" class="text">Google</span> 嵌套 a 不允许嵌套 div 这种约束属于语义嵌套约束,与之区别的约束还有严 格嵌套约束,比如 a 不允许嵌套 a 。 严格嵌套约束在所有的浏览器下都不被允许;而语义嵌套约束,浏览器 大多会容错处理,生成的文档树可能相互不太一样。 语义嵌套约束 <li> 用于 <ul> 或 <ol> 下; <dd> , <dt> 用于 <dl> 下; <thead> , <tbody> , <tfoot> , <tr> , <td> 用于 <table> 下; 严格嵌套约束 inline-Level 元素,仅可以包含文本或其它 inline-Level 元素; <a> 里不可以嵌套交互式元素 <a> 、 <button> 、 <select> 等; <p> 里不可以嵌套块级元素 <div> 、 <h1>~ 本文档使用 书栈(BookStack.CN) 构建 - 16 -

17.通用约定 <h6> 、 <p> 、 <ul>/<ol>/<li> 、 <dl>/<dt>/<dd> 、 <form> 等。 更多详情,参考WEB标准系列-HTML元素嵌套 布尔值属性 HTML5 规范中 disabled 、 checked 、 selected 等属性不用设置 值。 1. <input type="text" disabled> 2. 3. <input type="checkbox" value="1" checked> 4. 5. <select> 6. <option value="1" selected>1</option> 7. </select> 本文档使用 书栈(BookStack.CN) 构建 - 17 -

18.语义化 语义化 语义化 常见标签语义 示例 语义化 没有 CSS 的 HTML 是一个语义系统而不是 UI 系统。 通常情况下,每个标签都是有语义的,所谓语义就是你的衣服分为外 套, 裤子,裙子,内裤等,各自有对应的功能和含义。所以你总不能 把内裤套在脖子上吧。— 一丝 此外语义化的 HTML 结构,有助于机器(搜索引擎)理解,另一方面 多人协作时,能迅速了解开发者意图。 常见标签语义 标签 语义 <p> 段落 <h1> <h2> <h3> ... 标题 <ul> 无序列表 <ol> 有序列表 <blockquote> 大段引用 <cite> 一般引用 <b> 为样式加粗而加粗 <strong> 为强调内容而加粗 <i> 为样式倾斜而倾斜 <em> 为强调内容而倾斜 code 代码标识 abbr 缩写 本文档使用 书栈(BookStack.CN) 构建 - 18 -

19.语义化 示例 将你构建的页面当作一本书,将标签的语义对应的其功能和含义; 书的名称: <h1> 书的每个章节标题: <h2> 章节内的文章标题: <h3> 小标题/副标题: <h4> <h5> <h6> 章节的段落: <p> 更多语义化的内容,参考 sofish 写的文章 这样去写你的 HTML。 本文档使用 书栈(BookStack.CN) 构建 - 19 -

20.HEAD HEAD HEAD 文档类型 语言属性 字符编码 IE 兼容模式 SEO 优化 viewport iOS 图标 favicon HEAD 模板 HEAD 文档类型 为每个 HTML 页面的第一行添加标准模式(standard mode)的声 明, 这样能够确保在每个浏览器中拥有一致的表现。 1. <!DOCTYPE html> 语言属性 为什么使用 lang=”zh-cmn-Hans” 而不是我们通常写的 lang=”zh-CN” 呢? 请参考知乎上的讨论: 网页头部的声明应该是用 lang=”zh” 还是 lang=”zh-cn”? 1. <!-- 中文 --> 2. <html lang="zh-Hans"> 3. 本文档使用 书栈(BookStack.CN) 构建 - 20 -

21.HEAD 4. <!-- 简体中文 --> 5. <html lang="zh-cmn-Hans"> 6. 7. <!-- 繁体中文 --> 8. <html lang="zh-cmn-Hant"> 9. 10. <!-- English --> 11. <html lang="en"> 字符编码 以无 BOM 的 utf-8 编码作为文件格式; 指定字符编码的 meta 必须是 head 的第一个直接子元素;请参 考前端观察的博文: HTML5 Charset 能用吗? 1. <html> 2. <head> 3. <meta charset="utf-8"> 4. ...... 5. </head> 6. <body> 7. ...... 8. </body> 9. </html> IE 兼容模式 优先使用最新版本的IE 和 Chrome 内核 1. <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> SEO 优化 1. <head> 2. <meta charset="utf-8"> 本文档使用 书栈(BookStack.CN) 构建 - 21 -

22.HEAD 3. <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> 4. <!-- SEO --> 5. <title>Style Guide</title> 6. <meta name="keywords" content="your keywords"> 7. <meta name="description" content="your description"> 8. <meta name="author" content="author,email address"> 9. </head> viewport viewport : 一般指的是浏览器窗口内容区的大小,不包含工具 条、选项卡等内容; width : 浏览器宽度,输出设备中的页面可见区域宽度; device-width : 设备分辨率宽度,输出设备的屏幕可见宽度; initial-scale : 初始缩放比例; maximum-scale : 最大缩放比例; 为移动端设备优化,设置可见区域的宽度和初始缩放比例。 1. <meta name="viewport" content="width=device-width, initial- scale=1.0"> iOS 图标 apple-touch-icon 图片自动处理成圆角和高光等效果; apple-touch-icon-precomposed 禁止系统自动添加效果, 直接显示设计原图; 1. <!-- iPhone 和 iTouch,默认 57x57 像素,必须有 --> 2. <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon- 57x57-precomposed.png"> 3. 4. <!-- iPad,72x72 像素,可以没有,但推荐有 --> 5. <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon- 本文档使用 书栈(BookStack.CN) 构建 - 22 -

23.HEAD 72x72-precomposed.png" sizes="72x72"> 6. 7. <!-- Retina iPhone 和 Retina iTouch,114x114 像素,可以没有,但推荐有 -- > 8. <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon- 114x114-precomposed.png" sizes="114x114"> 9. 10. <!-- Retina iPad,144x144 像素,可以没有,但推荐有 --> 11. <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon- 144x144-precomposed.png" sizes="144x144"> favicon 在未指定 favicon 时,大多数浏览器会请求 Web Server 根目录 下的 favicon.ico 。为了保证 favicon 可访问,避免404,必须 遵循以下两种方法之一: 在 Web Server 根目录放置 favicon.ico 文件; 使用 link 指定 favicon; 1. <link rel="shortcut icon" href="path/to/favicon.ico"> HEAD 模板 1. <!DOCTYPE html> 2. <html lang="zh-cmn-Hans"> 3. <head> 4. <meta charset="utf-8"> 5. <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> 6. <title>Style Guide</title> 7. <meta name="description" content="不超过150个字符"> 8. <meta name="keywords" content=""> 9. <meta name="author" content="name, email@gmail.com"> 10. 11. <!-- 为移动设备添加 viewport --> 12. <meta name="viewport" content="width=device-width, initial- 本文档使用 书栈(BookStack.CN) 构建 - 23 -

24.HEAD scale=1.0"> 13. 14. <!-- iOS 图标 --> 15. <link rel="apple-touch-icon-precomposed" href="/apple-touch- icon-57x57-precomposed.png"> 16. 17. <link rel="alternate" type="application/rss+xml" title="RSS" href="/rss.xml" /> 18. <link rel="shortcut icon" href="path/to/favicon.ico"> 19. </head> 本文档使用 书栈(BookStack.CN) 构建 - 24 -

25.CSS CSS CSS CSS 本文档使用 书栈(BookStack.CN) 构建 - 25 -

26.通用约定 通用约定 通用约定 代码组织 Class 和 ID 声明块格式 声明顺序 引号使用 媒体查询(Media query)的位置 不要使用 @import 链接的样式顺序: 无需添加浏览器厂商前缀 通用约定 代码组织 以组件为单位组织代码段; 制定一致的注释规范; 组件块和子组件块 以及 声明块 之间使用一空行分隔, 子组件块 之间三 空行分隔; 如果使用了多个 CSS 文件,将其按照组件而非页面的形式分拆, 因为页面会被重组,而组件只会被移动; 良好的注释是非常重要的。请留出时间来描述组件(component)的 工作方式、局限性和构建它们的方法。不要让你的团队其它成员 来猜 测一段不通用或不明显的代码的目的。 提示:通过配置编辑器,可以提供快捷键来输出一致认可的注释模式。 本文档使用 书栈(BookStack.CN) 构建 - 26 -

27.通用约定 1. /* ========================================================================== 2. 组件块 3. ============================================================================ */ 4. 5. /* 子组件块 6. ============================================================================ */ 7. .selector { 8. padding: 15px; 9. margin-bottom: 15px; 10. } 11. 12. 13. 14. /* 子组件块 15. ============================================================================ */ 16. .selector-secondary { 17. display: block; /* 注释*/ 18. } 19. 20. .selector-three { 21. display: span; 22. } Class 和 ID 使用语义化、通用的命名方式; 使用连字符 - 作为 ID、Class 名称界定符,不要驼峰命名法和 下划线; 避免选择器嵌套层级过多,尽量少于 3 级; 本文档使用 书栈(BookStack.CN) 构建 - 27 -

28.通用约定 避免选择器和 Class、ID 叠加使用; 出于性能考量,在没有必要的情况下避免元素选择器叠加 Class、ID 使用。 元素选择器和 ID、Class 混合使用也违反关注分离原则。如果HTML 标签修改了,就要再去修改 CSS 代码,不利于后期维护。 1. /* Not recommended */ 2. .red {} 3. .box_green {} 4. .page .header .login #username input {} 5. ul#example {} 6. 7. /* Recommended */ 8. #nav {} 9. .box-video {} 10. #username input {} 11. #example {} 声明块格式 选择器分组时,保持独立的选择器占用一行; 声明块的左括号 { 前添加一个空格; 声明块的右括号 } 应单独成行; 声明语句中的 : 后应添加一个空格; 声明语句应以分号 ; 结尾; 一般以逗号分隔的属性值,每个逗号后应添加一个空格; rgb() 、 rgba() 、 hsl() 、 hsla() 或 rect() 括号内的值,逗 号分隔,但逗号后不添加一个空格; 对于属性值或颜色参数,省略小于 1 的小数前面的 0 (例 如, .5 代替 0.5 ; -.5px 代替 -0.5px ); 十六进制值应该全部小写和尽量简写,例如, #fff 代替 本文档使用 书栈(BookStack.CN) 构建 - 28 -

29.通用约定 #ffffff ; 避免为 0 值指定单位,例如,用 margin: 0; 代替 margin: 0px; ; 1. /* Not recommended */ 2. .selector, .selector-secondary, .selector[type=text] { 3. padding:15px; 4. margin:0px 0px 15px; 5. background-color:rgba(0, 0, 0, 0.5); 6. box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF 7. } 8. 9. /* Recommended */ 10. .selector, 11. .selector-secondary, 12. .selector[type="text"] { 13. padding: 15px; 14. margin-bottom: 15px; 15. background-color: rgba(0,0,0,.5); 16. box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff; 17. } 声明顺序 相关属性应为一组,推荐的样式编写顺序 1. Positioning 2. Box model 3. Typographic 4. Visual 由于定位(positioning)可以从正常的文档流中移除元素,并且还 能覆盖盒模型(box model)相关的样式,因此排在首位。盒模型决 定了组件的尺寸和位置,因此排在第二位。 本文档使用 书栈(BookStack.CN) 构建 - 29 -