前端开发规范(HTML,CSS,JS,VUE)

开发规范

一．HTML规范

1. 基本原则

• 结构、样式、行为分离
  尽量确保文档和模板只包含 HTML 结构，样式都放到样式表里，行为都放到脚本里。

• 缩进
  统一两个空格缩进（总之缩进统一即可），不要使用 Tab 或者 Tab、空格混搭。

• 文件编码
  使用不带 BOM 的 UTF-8 编码。在 HTML中指定编码；无需使用 @charset指定样式表的编码，它默认为UTF-8（参考 @charset）；

• 一律使用小写字母

image.png

• 注释

  • 统一注释
    通过配置编辑器，可以提供快捷键来输出一致认可的注释模式。
    例如：VS code 快捷键 ctrl+/

注释内容左右两边保留和注释符号有1个空格位，在注释内容内不允许再出现中划线-

• 按模块添加注释
  image.png

  注释风格保持与原生HTML的语法相似：成对出现

2. HTML 相关

• 标签

  • 自闭合（self-closing）标签，无需闭合 ( 例如： img input br hr 等 )；
  • 可选的闭合标签（closing tag），需闭合 ( 例如：
  或 )；
  • 尽量减少标签数量；

• 格式

  • 将每个块元素、列表元素或表格元素都放在新行；
  • inline元素视情况换行，以长度不超过编辑器一屏为宜；

  • 每个子元素都需要相对其父级缩进（参见缩进约定）。

    
    
    image.png

• 模块化

• 每个模块必须有一个模块名；

• 每个模块的基本组成部分应该一致；

• 模块的子节点类名需带上模块名（防止模块间嵌套时产生不必要的覆盖）；

• 孙辈节点无需再带模块名。

  image.png
  其中.m-detail-hd, .m-detail-bd, .m-detail-ft为可选，视具体模块情况决定是否需要抽象为这种 头，中，尾 的结构

• class 与 id

  • class 应以功能或内容命名，不以表现形式命名；
  • class 与 id 单词字母小写，多个单词组成时，采用中划线-分隔，不要驼峰命名法和下划线；
  • 使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class；

• 属性顺序
  HTML 属性应该按照特定的顺序出现以保证易读性。
  id > class > name > data-xxx > src,for,type,href > title,alt > aria-xxx,role

• 引号
  

  属性的定义，统一使用双引号。
  image.png

• 嵌套
  a 不允许嵌套 div这种约束属于语义嵌套约束，与之区别的约束还有严格嵌套约束，比如a 不允许嵌套 a。
  严格嵌套约束在所有的浏览器下都不被允许；而语义嵌套约束，浏览器大多会容错处理，生成的文档树可能相互不太一样。
  语义嵌套约束

  • 用于
    或
    下；
    1. ,
       用于

       下；

    2. , , , , 用于 下；
       严格嵌套约束
       inline-Level 元素，仅可以包含文本或其它 inline-Level 元素;
       里不可以嵌套交互式元素、、等;

       里不可以嵌套块级元素

       、

       ~

       、

       、

       /
       /
       1. 、

          /

          /

          、

          等。

       更多详情，参考WEB标准系列-HTML元素嵌套

       • 布尔值属性
         HTML5 规范中 disabled、checked、selected 等属性不用设置值。
         image.png
       • 语义化
         没有 CSS 的 HTML 是一个语义系统而不是 UI 系统。通常情况下，每个标签都是有语义的，各自有对应的功能和含义。语义化的 HTML 结构，有助于机器（搜索引擎）理解，另一方面多人协作时，能迅速了解开发者意图。

       • head
         

         文档类型。为每个 HTML 页面的第一行添加标准模式（standard mode）的声明， 这样能够确保在每个浏览器中拥有一致的表现。
         image.png
       • 语言属性
         lang属性的取值应该遵循BCP 47 - Tags for Identifying Languages。
         image.png
       • 字符编码
         • 以无 BOM 的 utf-8 编码作为文件格式;
         • 指定字符编码的 meta 必须是 head 的第一个直接子元素；
           image.png

       • IE 兼容模式
         

         优先使用最新版本的IE 和 Chrome 内核
         image.png

       • SEO 优化
         image.png
       • viewport
         • viewport: 一般指的是浏览器窗口内容区的大小，不包含工具条、选项卡等内容；
         • width: 浏览器宽度，输出设备中的页面可见区域宽度；
         • device-width: 设备分辨率宽度，输出设备的屏幕可见宽度；
         • initial-scale: 初始缩放比例；
         • maximum-scale: 最大缩放比例；

       为移动端设备优化，设置可见区域的宽度和初始缩放比例。

       image.png

       • head模板
         image.png

       二．CSS 规范

       1. class和id

       • class应以功能或内容命名，不以表现形式命名；
       • class 与 id 单词字母小写，多个单词组成时，采用中划线-分隔，不要驼峰命名法和下划线；
       • 使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class；
       • 避免选择器和 Class、ID 叠加使用；
       • 避免选择器嵌套层级过多，尽量少于 3 级；
       • 重构工程师只允许使用class；

       出于性能考量，在没有必要的情况下避免元素选择器叠加 Class、ID 使用。元素选择器和ID、Class 混合使用也违反关注点分离原则。如果HTML标签修改了，就要再去修改 CSS 代码，不利于后期维护。

       2. 命名规范

       • 组成元素
         • 【强制】命名必须由小写单词、中划线-组成。不允许使用大写字母或_、不允许通过1、2、3等序号进行命名
         • 【强制】不允许使用拼音（约定俗成的除外，如：youku, baidu），尤其是缩写的拼音、拼音与英文的混合。应该采用更简明有语义的英文单词进行组合,应该用意义命名，而不是样式显示结果命名;不要用抽象的晦涩的命名.
           image.png
       • 词汇规范
         • 不依据表现形式来命名；
         • 可根据内容来命名；

         • 可根据功能来命名；
           image.png
       • 缩写规范
         • 保证缩写后还能较为清晰保持原单词所能表述的意思；

         • 使用业界熟知的或者约定俗成的；
           image.png
       • 前缀规范

       前缀	说明	示例
       g-	全局通用样式命名，前缀g全称为global，一旦修改将影响全站样式	g-mod
       m-	模块命名方式	m-detail
       ui-	组件命名方式	ui-selector
       js-	所有用于纯交互的命名，不涉及任何样式规则	js-switch

       image.png

       3. 书写格式

       • 【强制】选择器与大括号之间保留一个空格；
       • 【强制】分号之后保留一个空格；
       • 【强制】逗号之后保留一个空格；
       • 【强制】所有规则需换行；
       • 【强制】多组选择器之间需换行；
       • 【强制】使用单引号，不允许使用双引号；
       • 【强制】除字体设置外，CSS文件中的所有的代码都应该小写；
       • 【强制】除了重置浏览器默认样式外，禁止直接为html tag添加css样式设置;
       • 【强制】每一条规则应该确保选择器唯一，禁止直接为全局.nav、.header、.body等类设置属性;

       4. 书写规则

       • 【强制】每条规则结束后都必须加上分号；
       • 如果属性值为0，则不需要为0加单位；
       • HEX颜色值写法：将所有的颜色值小写，可以缩写的缩写至3位。

       5. 注释规范

       • 保持注释内容与星号之间有一个空格的距离。

       • 文件顶部注释
         image.png

       • 单行注释

         
         
         image.png

       • 模块注释
         

         模块注释必须单独写在一行
         image.png
       • 单行注释与多行注释,单行注释可以写在单独一行，注释中的每一行长度不超过40个汉字，或者80个英文字符。

       • 特殊注释
         

         用于标注修改、待办等信息
         image.png

       6. 声明顺序

       相关属性应为一组，推荐的样式编写顺序

       • Positioning定位：可以使一个元素脱离正常文本流，并且覆盖盒模型相关的样式
       • Box model盒模型：决定了一个组件的大小和位置
       • Typographic 排版
       • Visual 外观

       由于定位（positioning）可以从正常的文档流中移除元素，并且还能覆盖盒模型（box model）相关的样式，因此排在首位。盒模型决定了组件的尺寸和位置，因此排在第二位。
       

       其他属性只是影响组件的内部（inside）或者是不影响前两组属性，因此排在后面。
       image.png

       三．JS规范

       1. 命名规范

       • 【强制】代码中命名不能以下划线或美元符开始，也不能以下划线或美元符结束
       • 【强制】代码中严禁使用拼音与英文混合的方式，更不允许直接使用中文方式。纯拼音命名方式也要避免采用（国际通用的名称可视为英文，如：taobao，alibaba等）
       • 【强制】类名使用UpperCamelCase风格，使用名词
         image.png
         image.png
       • 私有属性、变量和方法以下划线_开头。

       • 私有属性、变量和方法以下划线_开头。
         image.png
       • 【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式 如：localValue，getMessage()。方法名使用动宾短语。
         image.png
         image.png
         image.png

       • 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长
         image.png
       • boolean 类型的变量使用 is 或 has 开头。
         image.png
       • Promise 对象用动宾短语的进行时表达。
         image.png
       • 【强制】杜绝完全不规范的缩写，避免望文不知义
       • let、const与var
         ES6 新增了let命令，用来声明变量。它的用法类似于var，但是所声明的变量，只在let命令所在的代码块内有效。
         工程开发中，除部分常量使用const声明外，其余全部使用let，不使用var；
         var有以下缺点：变量提升。不适合循环等局部运算(容易导致很多无法预料的结果)
       • 【推荐】为了达到代码自解释的目标，任何定义编程元素在命名时使用尽量完整单词组合来表达其意

       2. 注释规范

       • 【强制】类，类属性，类方法使用/**内容*/格式，不得使用// xxx方式
       • 单行注释
         必须独占一行。//后跟一个空格，缩进与下一行被注释说明的代码一致。
       • 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。参数和返回值注释必须包含类型信息和说明，当函数是内部函数，外部不可访问时，可以使用 @inner 标识。方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
         image.png
       • 代码修改同时，注释也要进行相应修改，尤其是参数、返回值、核心逻辑等的修改。说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
       • 特殊注释标记
         请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
         待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]） 表示需要实现，但目前还未实现的功能。
         错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]） 在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

       3. 风格规范

       • 空格与运算符
         通常运算符 ( = + - * / ) 前后需要添加空格，任何二目、三目运算符的左右两边都需要加一个空格。
         image.png

       • 一条语句通常以分号作为结束符。
         image.png
       • 复杂语句的通用规则:
         • 将左花括号放在第一行的结尾。
         • 左花括号前添加一空格。
         • 将右花括号独立放在一行。
         • 不要以分号结束一个复杂的声明。
       image.png
       • 对象规则
         • 将左花括号与类名放在同一行。
         • 冒号与属性值间有个空格。
         • 字符串使用双引号，数字不需要。
         • 最后一个属性-值对后面不要添加逗号。
         • 将右花括号独立放在一行，并以分号作为结束符号
       image.png

       四．Vue规范

       1. 详见：https://cn.vuejs.org/v2/style-guide/