前端开发规范手册

下载 1

ccone

发布于

1950

人观看

#信息技术

该手册主要实现的目标：代码一致性和最佳实践。

展开查看详情

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.  2. <img src="google.png" alt="Google"> 3. 4.  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.  2. <script src="//www.google.com/js/gweb/analytics/autotrack.js"> </script> 3. 4.  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.  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.  10. <span class="avatar"> 11. <img src="..."> 12. </span> 本文档使用书栈(BookStack.CN) 构建 - 14 -

15 .通用约定 13. 14.  15. <img class="avatar" src="..."> Class 与 ID class 应以功能或内容命名，不以表现形式命名； class 与 id 单词字母小写，多个单词组成时，采用中划线 - 分隔；使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class； 1.  2. <div class="j-hook left contentWrapper"></div> 3. 4.  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.  2. <span id='j-hook' class=text>Google</span> 3. 4.  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.  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.  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.  2. <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon- 57x57-precomposed.png"> 3. 4.  5. <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon- 本文档使用书栈(BookStack.CN) 构建 - 22 -

23 .HEAD 72x72-precomposed.png" sizes="72x72"> 6. 7.  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.  12. <meta name="viewport" content="width=device-width, initial- 本文档使用书栈(BookStack.CN) 构建 - 23 -

24 .HEAD scale=1.0"> 13. 14.  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 -

20点赞

5收藏

1下载