前端代码编写规范.doc_咨信网zixin.com.cn

资源描述

前端代码编写规范命名规则 1. 项目名称项目名称驼峰式命名。例：myProject 2. 目录命名采用单数命名法。例：css img font js 3. JS文件命名字母全部小写，单词之间用“-”链接。例：popup-window.js 4. CSS文件命名字母全部小写，单词之间用“-”链接。例：popup-window.css 5. HTML文件命名文件名称驼峰式命名。例：riverMonitor.html HTML 1. 语法缩进使用Tab（4个空格）; 解释：对于非HTML标签之间的缩进,比如script或style标签内容缩进，与script或style标签的缩进同级。 <style> /* 样式内容的第一级缩进与所属的 style 标签对齐 */ ul { padding: 0; } </style> <ul> <li>first</li> <li>second</li> </ul> <script> // 脚本代码的第一级缩进与所属的 script 标签对齐 require(['app'], function (app) { app.init(); }); </script> 嵌套的节点应该缩进; 在属性上使用双引号（字符串拼接除外）; 属性名全小写，用“-”做分隔符; 自动闭合标签处不能使用斜线。 <html> <head> <title>Page title</title> </head> <body> <img src="images/company_logo.png" alt="Company"> <h1 class="hello-world">Hello, world!</h1> </body> </html> 2. HTML5 doctype 页面开头的doctype大写，html小写。例：<!DOCTYPE html> <!DOCTYPE html> <html> ... </html> 3. 字符编码采用UTF-8的编码格式。例：<meta charset=”UTF-8”> <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> </head> ... </html> 4. 引入CSS,JS CSS引入使用<link> <link rel="stylesheet" href="code-guide.css"> JS 引入使用<script> <script type="text/javascript" href="code-guide.js"></script> 页面不允许出现style标签。 5. 属性 1. 属性名必须使用小写字母  <table cellspacing="0">...</table>  <table cellSpacing="0">...</table 2. 属性值必须使用双引号包围不允许使用单引号。  <script src="esl.js"></script>  <script src='esl.js'></script> <script src=esl.js></script> 6. 属性顺序 class id name data-* src,for,type,href,value,max-length,max,min,pattern placeholder,title,alt aria-*,role required,readonly,disabled 7. 标签标签名必须使用小写字母  <p>Hello StyleGuide!</p>  <P>Hello StyleGuide!</P> 1．对于无需自闭合的标签，不允许自闭合解释：常见无需自闭合标签有 input、br、img、hr 等。  <input type="text" name="title">  <input type="text" name="title" /> 2. 标签使用必须符合标签嵌套规则解释：比如div不得置于p中，tbody必须置于table中。 ul 标签包含着 li、dl 标签包含着 dt 和 dd。 3. 标签使用必须符合标签嵌套规则常见标签语义： P –段落 h1,h2,h3,h4,h5,h6–层级标题 strong,em–强调 ins–插入 del–删除 abbr–缩写 code–代码标识 cite–引述来源作品的标题 q–引用 blockquote–一段长篇引用 ul–无序列表 ol–有序列表 dl,dt,dd–定义列表 8. 图片禁止 img 的 src 取值为空。延迟加载的图片也要增加默认的 src。解释： src 取值为空，会导致部分浏览器重新加载一次当前页面，参考： [建议] 避免为 img 添加不必要的 title 属性。解释：多余的 title 影响看图体验，并且增加了页面尺寸。 [建议] 为重要图片添加 alt 属性。解释：可以提高图片加载失败时的用户体验。 [建议] 添加 width 和 height 属性，以避免页面抖动。 [建议] 有下载需求的图片采用 img 标签实现，无下载需求的图片采用 CSS 背景图实现。解释： 1. 产品 logo、用户头像、用户产生的图片等有潜在下载需求的图片，以 img 形式实现，能方便用户下载。 2. 无下载需求的图片，比如：icon、背景、代码使用的图片等，尽可能采用 CSS 背景图实现。 9. 表单 1．控件标题 [强制] 有文本标题的控件必须使用 label 标签将其与其标题相关联。解释：有两种方式： 1. 将控件置于 label 内。 2. label 的 for 属性指向控件的 id。推荐使用第一种，减少不必要的 id。如果 DOM 结构不允许直接嵌套，则应使用第二种。示例： <label><input type="checkbox" name="confirm" value="on"> 我已确认上述条款</label> <label for="username">用户名：</label> <input type="textbox" name="username" id="username"> 2．按钮 [强制] 使用 button 元素时必须指明 type 属性值。解释： button 元素的默认 type 为 submit，如果被置于 form 元素中，点击后将导致表单提交。为显示区分其作用方便理解，必须给出 type 属性。示例： <button type="submit">提交</button> <button type="button">取消</button> [建议] 尽量不要使用按钮类元素的 name 属性。解释：由于浏览器兼容性问题，使用按钮的 name 属性会带来许多难以发现的问题。具体情况可参考此文。 3．可访问性 (A11Y) [建议] 负责主要功能的按钮在 DOM 中的顺序应靠前。解释：负责主要功能的按钮应相对靠前，以提高可访问性。如果在 CSS 中指定了 float: right 则可能导致视觉上主按钮在前，而 DOM 中主按钮靠后的情况。示例：  <style> .buttons .button-group { float: right; } </style> <div class="buttons"> <div class="button-group"> <button type="submit">提交</button> <button type="button">取消</button> </div> </div>  <style> .buttons button { float: right; } </style> <div class="buttons"> <button type="button">取消</button> <button type="submit">提交</button> </div> [建议] 当使用 JavaScript 进行表单提交时，如果条件允许，应使原生提交功能正常工作。解释：当浏览器 JS 运行错误或关闭 JS 时，提交功能将无法工作。如果正确指定了 form 元素的 action 属性和表单控件的 name 属性时，提交仍可继续进行。示例： <form action="/login" method="post"> <p><input name="username" type="text" placeholder="用户名"></p> <p><input name="password" type="password" placeholder="密码"></p> </form> [建议] 在针对移动设备开发的页面时，根据内容类型指定输入框的 type 属性。解释：根据内容类型指定输入框类型，能获得能友好的输入体验。示例： <input type="date"> 10. 多媒体 [建议] 当在现代浏览器中使用 audio 以及 video 标签来播放音频、视频时，应当注意格式。解释：音频应尽可能覆盖到如下格式： · MP3 · WAV · Ogg 视频应尽可能覆盖到如下格式： · MP4 · WebM · Ogg [建议] 在支持 HTML5 的浏览器中优先使用 audio 和 video 标签来定义音视频元素。 [建议] 使用退化到插件的方式来对多浏览器进行支持。示例： <audio controls> <source src="audio.mp3" type="audio/mpeg"> <source src="audio.ogg" type="audio/ogg"> <object width="100" height="50" data="audio.mp3"> <embed width="100" height="50" src="audio.swf"> </object> </audio> <video width="100" height="50" controls> <source src="video.mp4" type="video/mp4"> <source src="video.ogg" type="video/ogg"> <object width="100" height="50" data="video.mp4"> <embed width="100" height="50" src="video.swf"> </object> </video> [建议] 只在必要的时候开启音视频的自动播放。 [建议] 在 object 标签内部提供指示浏览器不支持该标签的说明。示例： <object width="100" height="50" data="something.swf">DO NOT SUPPORT THIS TAG</object> 11. js生成标签在js文件中生成标签让内容更难查找，更难编辑，性能更差，应该尽量避免这种情况的出现 12. 减少标签数量在编写HTML代码时，需要尽量避免多余的父节点; 很多时候，需要通过迭代和重构来使HTML变得更少; 任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。例： <span class="avatar"> <img src="..."> </span>  <img class="avatar" src="..."> 13. 使用高于完美尽量组训HTML标准和语义，但是不应该以浪费实用性作为代价；任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。 14. 整体结构 HTML基础设施 · 文件应以“<!DOCTYPE ......>”首行顶格开始，推荐使用“<!DOCTYPE html>”。 · 必须申明文档的编码charset，且与文件本身编码保持一致，推荐使用UTF-8编码<meta charset="utf-8"/>。 · 根据页面内容和需求填写适当的keywords和description。 · 页面title是极为重要的不可缺少的一项。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <title>NEC：更好的CSS方案</title> <meta name="keywords" content=""/> <meta name="description" content=""/> <meta name="viewport" content="width=device-width"/> <link rel="stylesheet" href="css/style.css"/> <link rel="shortcut icon" href="img/favicon.ico"/> <link rel="apple-touch-icon" href="img/touchicon.png"/> </head> <body> </body> </html> 结构顺序和视觉顺序基本保持一致 · 按照从上至下、从左到右的视觉顺序书写HTML结构。 · 有时候为了便于搜索引擎抓取，我们也会将重要内容在HTML结构顺序上提前。 · 用div代替table布局，可以使HTML更具灵活性，也方便利用CSS控制。 · table不建议用于布局，但表现具有明显表格形式的数据，table还是首选。结构、表现、行为三者分离，避免内联 · 使用link将css文件引入，并置于head中。 · 使用script将js文件引入，并置于body底部。保持良好的简洁的树形结构 · 每一个块级元素都另起一行，每一行都使用Tab缩进对齐（head和body的子元素不需要缩进）。删除冗余的行尾的空格。 · 使用4个空格代替1个Tab（大多数编辑器中可设置）。 · 对于内容较为简单的表格，建议将tr写成单行。 · 你也可以在大的模块之间用空行隔开，使模块更清晰。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 <body>  <div class="m-side"> <div class="side"> <div class="sidein">  <div class="sideblk"> <div class="m-hd3"><h3 class="tit">热门标签</h3> </div> ... </div>  <div class="sideblk"> <div class="m-hd3"><h3 class="tit">最热TOP5</h3> <a href="#" class="s-fc02 f-fr">更多»</a></div> ... </div> </div> </div> </div>  </body> CSS 1. 缩进缩进使用Tab（4个空格）。 .element { position: absolute; top: 10px; left: 10px; border-radius: 10px; width: 50px; height: 50px; } 2. 分号每个属性声明末尾都要加分号。 .element { width: 20px; height: 20px; } 3. 空行文件最后保留一个空行; ‘}’结尾后跟一个空行。 .element { ... } .dialog { color: red; &:after { ... } } 4. 换行每个属性独占一行。 .element { color: red; background-color: black; } 5. 注释注释统一用‘/**/’，具体参照例中写法; 缩进与下一行代码保持一致; 可位于一个代码行的末尾,与代码间隔一个空格。例：/* Modal header */ .modal-header { /* 50px */ width: 50px; color: red; /* color red */ } 6. 引号最外层统一使用双引号; url的内容要用引号; 属性选择器找那个的属性值需要引号。 .element:after { content: ""; background-image: url("logo.png"); } li[data-type="single"] { ... } 7. 命名命名使用小写字母，以“-”分隔; Id采用驼峰式命名; /* class */ .element-content { ... } /* id */ #myDialog { ... } 8. 颜色颜色十六进制用小写字母，尽量使用简写; 例：.element { color: #abcdef; background-color: #012; } 9. 杂项不允许有空的规则; 元素选择器用小写字母; 属性值‘0’后面不加单位; 不要在一个文件里出现两个相同的规则; 用border:0; 代替 border:none; ; 尽量少用“*”选择器。 JavaScript 1. 缩进缩进使用Tab（4个空格） var x = 1, y = 1; if (x < y) { x += 10; } else { x += 1; } 2. 分号以下几种情况后需加分号：变量声明表达式 return throw break continue do-while /* var declaration */ var x = 1; /* expression statement */ x++; /* do-while */ do { x++; } while (x < 10); 3. 空行以下几种情况需要空行：变量声明后; 注释前; 代码块后; 文件最后保留一个空行。 4. 换行以下几种情况不需要换行：解释：超长的不可分割的代码允许例外,比如复杂的正则表达式, 长字符串不在例外之列。下列关键字后：else,catch,finally 代码块‘{’前以下几种情况需要换行：代码块‘{’后和‘}’前变量复制后 5. 单行注释双斜线后，必须跟一个空格; 缩进与下一行代码保持一致; 可位于一个代码行的末尾,与代码间隔一个空格。 if (condition) { // if you made it here, then all security checks passed allowed(); } var zhangsan = 'zhangsan'; // one space after code 6. 多行注释最少三行，“*”后跟一个空格。 /* * one space after '*' */ var x = 1; 7. 文件注释文件顶部必须包含文件注释，用@file标识文件说明 /** * @file Describe the file */ 8. 命名空间注释命名空间使用@namespace标识 /** * @namespace */ var util = {}; 9．类注释 /** * parm * return */ function Developer() { // constructor body } 10. 变量命名变量名采用驼峰式命名（除对象的属性外） var thisIsMyName; ‘id’在变量名中‘i’大写例：Id var goodId; ‘url’在变量名中全大写 var reportURL; ‘Android’在变量名中大写第一个字母 var AndroidVersion; ‘iOS’在变量名中小写第一个字母，大写后两个字母 var iOSVersion; 常量全大写，用下划线链接 var MAX_COUNT = 10; 构造函数，大写第一个字母 function Person(name) { this.name = name; } 11. 变量声明每个var只能声明一个变量。 var hangModules = []; var missModules = []; var visited = {}; 12. 数组、对象对象属性名不需要加引号; 对象以缩进的形式书写,不要写在一行。 var a = { b: 1, c: 2 }; 13. 括号下列关键字后必须有大括号（即使代码块的内容只有一行） If，else,for,while,do,switch,try,catch,finally,with。 14. Null 使用场景：初始化一个将来可能被赋值为对象的变量与已经初始化的变量做比较作为一个参数为对象的函数的调用传参作为一个返回对象的函数的返回值不使用场景：不要用null来判断函数调用时有无传参不要与未初始化的变量做比较 // not good function test(a, b) { if (b === null) { // not mean b is not supply ... } } var a; if (a === null) { ... } // good var a = null; if (a === null) { ... } 15. Undefined 永远不要直接使用undefined进行变量判断; 使用typeof和字符串‘undefined’对变量进行判断。 // not good if (person == undefined) { ... } // good if (typeof person == 'undefined') { ... } 16. Jshint 比较用‘==’，‘!=’; if (a == 1) { a++; } 不要在内层作用域的代码里声明了变量,之后却访问了外层作用域的同名变量; // not good var x = 1; function test() { if (true) { var x = 0; } x += 1; } 变量不要先使用后声明; 不要在同个作用域下声明同名变量; 不要在一些不需要的地方加括号,例：delete(a.b); 不要使用未声明的变量; 数组中不要存在空元素; // not good var nums = []; for (var i = 0; i < 10; i++) { (function(i) { nums[i] = function(j) { return i + j; }; }(i)); } 不要声明了变量却不使用; 不要在循环内部声明函数; // not good function test() { console.log(x); var x = 1; } 17. 杂项不要混用Tab和Space; 不要在一处使用多个Tab或Space; 行尾不要有空白字符; 不允许有空的代码块。 // not good var a = 1; function Person() { // not good var me = this; // good var _this = this; // good var that = this; // good var self = this; } // good switch (condition) { case 1: case 2: ... break; case 3: ... // why fall through case 4 ... break; // why no default } // not good with empty block if (condition) { } E-JSON数据传输标准 JSON数据类型 JSON（JavaScript Object Notation）是一种轻量级，基于文本，语言无关的数据交换格式。其包括了基本数据类型4种和复合数据类型2种，共6种数据类型。在下面章节中，JSON数据类型的表示法为JSON+空格+数据类型，如：JSON Array。传输的数据，包括对象属性以及数组成员，必须(MUST) 是6种JSON数据类型之一。杜绝(MUST NOT) 使用function、Date等js对象类型。基本数据类型 · Number可以表示整数和浮点数。 · Boolean可以表示真假，值为true或false。 · String表示一个字符串。 · Null通常用于表示空对象。 "true"和true，这两个数据代表的是不同的数据类型。非字符串类型数据输出时一定不要(MUST NOT) 为两端加上双引号，否则可能产生不希望的后果（如if中判断"false"的结果是true）。其他容易产生错误的例子如：0和"0"等。复合数据类型 Object是无序的集合，以键值对的方式保持数据。一个Object中包含零到多个name/value的数据，数据间以逗号(,)分隔。name为String类型，value可以是任意类型的数据。 Object的最后一个元素之后一定不要(MUST NOT) 加上分隔符的逗号，否则可能导致解析出错。 Array(数组)为多个值的有序集合，数组元素间以逗号(,)分隔。 http响应头 status http响应的status 必须(MUST) 为200。通常JSON数据被用于通过XMLHttpRequest对象访问，通过javascript进行处理。返回错误的状态码可能导致错误不被响应，数据不被处理。 Content-Type Content-Type字段定义了响应体的类型。一般情况下，浏览器会根据该类型对内容进行正确的处理。对于传输JSON数据的响应，Content-Type 推荐(RECOMMENDED) 设置为"text/javascript"或"text/plain"。避免(MUST NOT) 将Context-Type设置为text/html，否则可能导致安全问题。 Content-Type中可以指定字符集。通常需要(SHOULD) 明确指定一个字符集。如果是通过XMLHTTPRequest请求的数据，并且字符编码为UTF-8时，可以不指定字符集。 Context-Type示例 text/javascript;charset=UTF-8 数据字段返回的数据包含在http响应体中。数据必须(MUST) 是一个JSON Object。该Object可能包含3个字段：status，statusInfo，data。 status status字段必须(MUST) 是一个不小于0的JSON Number整数，表示请求的状态。这个字段可以(SHOULD) 被省略，省略时和为0时表示同一含义。 0：表示server端理解了请求，成功处理并返回。非0：表示发生错误。可以(SHOULD) 根据错误类型扩展错误码。一个成功请求的status字段 { "status": 0, "data": "hello world!" } statusInfo statusInfo字段通常(SHOULD) 是一个JSON String或JSON Object，表示除了请求状态外server端想要对status做出的说明，使client端能够获取更多信息进行后续处理。这个字段是可选的(OPTIONAL) 。下面的两个例子中，statusInfo字段的信息都可以用于client端程序的后续处理，但是粒度和处理方式会有不同。 client端参数错误的statusInfo 简单说明的statusInfo： { "status": 1, "statusInfo": "参数错误" } 具有更多信息的statusInfo： { "status": 1, "statusInfo": { "text": "参数错误", "parameters": { "email": "电子邮件格式不正确" } } } data data字段可以是除JSON Null之外的任意JSON类型，表示请求返回的数据主体。这个字段是可选的(OPTIONAL) 。数据主体data包含了在请求成功时有意义的数据。一个查询姓名请求的返回数据 { "status": 0, "data": "Lily" } 键/值对象对于在一个JSON Object中表示键/值： · 键的属性名必须(MUST) 为name，杜绝(MUST NOT) 使用key或k · 值的属性名必须(MUST) 为value，杜绝(MUST NOT) 使用v。数据场景：键/值对象 { "name": "BMW", "value": 1 } 键/值有序集合键/值有序集合表示对事务或逻辑类型的抽象与分类。常见的应用场景有单选复选框集合，下拉菜单等。标准的键/值有序集合是一个JSON Array，集合中的每一项是一个JSON Object。项必须(MUST) 包含name和value属性。可以(MAY) 通过其他的属性修饰每一项的特殊信息，如selected。数据场景：键/值有序集合 [ { "name": "BMW", "value": 1 }, { "name": "Benz", "value": 2, "selected": true } ] 树树形数据用于表示层叠的数据结构。树型数据必须(MUST) 是一个JSON Object，代表树型数据的根节点。下面是标准定义的可选节点列表，不在列表中的属性可以(SHOULD) 自行扩展。树型数据结构的可选节点属性 · {Number|String} id - 节点的唯一标识。 · {String} text - 名称或用于显示的字符串。 · {Array} children - 子节点列表。数据场景：树型数据 { "id": 1, "text": "中国", "children": [ { "id": 10, "text": "北京", "children": [ { "id": 100, "text": "东城区" }, { "id": 101, "text": "西城区" }, { "id": 102, "text": "海淀区" } ...... ] }, { "id": 31, "text": "海南", "children": [ { "id": 600, "text": "海口"

展开阅读全文