ZoneTop

Appearance

HTML 与 CSS 编码规范 ​

目的 ​

为了保证所每个项目组编写出的程序都符合相同的规范，便于理解和维护，便于检查、减少出错概率，有助于成员间交流，保证一致性、统一性而建立的 HTML 与 CSS 编码规范。

范围 ​

该规范适用于所有基于前端项目。规范内容主要针对 CDN 模式下的文件，在 NPM 开发环境中 webpack 开发方式存在部分不同（详见 webpack 开发方式内容）。

文件格式 ​

文件统一使用无 BOM 的 UTF-8 编码。

代码格式规范 ​

在编辑器 vscode 中安装 Prettier（代码格式化工具），按照配置的标准格式化文件。以下罗列了规范内容。

  1. 使用 2 个空格进行缩进。
  2. 每行不得超过 120 个字符。
  3. 引入 CSS 时必须指明 rel="stylesheet"。
  4. 引入 CSS 和 JavaScript 时无须指明 type 属性。
  5. 引用外部资源的 URL 协议部分与页面相同，建议省略协议前缀。

HTML 编码规范 ​

  1. 页面必须包含  title  标签声明标题。
  2. 标签名必须使用小写字母。
  3. 对于无需自闭合的标签，不允许自闭合。
  4. 对  HTML5  中规定允许省略的闭合标签，不允许省略闭合标签。
  5. 标签使用必须符合标签嵌套规则。

CSS 编码规范 ​

  1. 不要随意使用 id。
  2. 属性值之后添加分号。
  3. 多个 selector 共用一个样式集，则多个 selector 必须写成多行形式。
  4. 使用单引号，不允许使用双引号。
  5. 每个声明结束都应该带一个分号，不管是不是最后一个声明。
  6. 除 16 进制颜色和字体设置外，CSS 文件中的所有的代码都应该小写。
  7. 除了重置浏览器默认样式外，禁止直接为 html tag 添加 css 样式设置。
  8. 每一条规则应该确保选择器唯一，禁止直接为全局.nav/.header/.body 等类设置属性。
  9. 0 后面不需要单位，比如 0px 可以省略成 0，0.8px 可以省略成.8px。
  10. 在保持代码解耦的前提下，尽量合并重复的样式。
  11. 没有边框时，不要写成 border:0，应该写成 border:none。

命名规范 ​

推荐采用 BEM 原则，及块（block）、元素（element）、修饰符（modifier）。

  1. B（block）：某一块展示/功能区域， 比如：.nav。
  2. E（element）：这块展示/功能区域里的某个元素， 比如: .nav**item。
  3. M（modifier）：某个元素或者某个块的状态， 比如：.nav—hide,.nav**item--active  等。

命名约定 ​

css
/*  块  */
.site-search  {
}
/*  元素  */
.site-search__field {
}
/*  修饰符  */
.site-search--full {
}


.person {
}


.person__hand {
}


.person--female {
}


.person--female__hand {
}


.person__hand--left {
}
html
<nav class="nav">
  <a href="#" class="nav__item nav__item--active">当前状态</a>  
  <a href="#" class="nav__item nav__item--hover">鼠标移上时的状态</a>  
  <a href="#" class="nav__item nav__item--normal">正常状态</a>
</nav>

npm 下  PostCSS 的写法

css
.nav  {
     & __item  {
       & --active  {
    }
    & --hover  {
    }
    & --normal  {
    }
  }
}

命名空间 ​

  1. o-：表示一个对象（Object），如  .o-layout。
  2. c-：表示一个组件（Component），指一个具体的、特定实现的  UI。如  .c-avatar。
  3. u-：表示一个通用工具（Utility），如  .u-hidden。
  4. t-：表示一个主题（Theme），如  .t-light。
  5. s-：表示一个上下文或作用域（Scope），如  .s-cms-content。
  6. is-，has-：表示一种状态或条件样式。如  .is-active
  7. _：表示一个  hack，如  ._important。
  8. js-：表示一个  JavaScript  钩子。如  .js-modal。
  9. qa-：表示测试钩子。

和 JavaScript 关联的  CSS 名称 ​

使用 js-  的类名命名方法。用这种方法来表明这个 DOM  元素和 JavaScript  代码的关联。

<div class="site-navigation js-site-navigation"></div>

const nav = document.querySelector('.js-site-navigation')

属性书写顺序 ​

属性值必须用双引号包围。   同一  rule set  下的属性在书写时，应按功能进行分组，并以  Formatting Model（布局方式、位置） > Box Model（尺寸） > Typographic（文本相关） > Visual（视觉效果）  的顺序书写，以提高代码的可读性。

  1. 布局相关属性包括 position / top / right / bottom / left / float / display / overflow  等
  2. 尺寸相关属性包括 border / margin / padding / width / height  等
  3. 文本相关属性包括 font / line-height / text-align / word-wrap  等
  4. 视觉相关属性包括 background / color / transition / list-style  等
  5. 如果包含  content  属性，应放在最前面。
css
.sidebar  {
  /* formatting model: positioning schemes / offsets / z-indexes / display / ...  */
  position: absolute;
  top: 50px;
  left: 0;
  overflow-x: hidden;


/* box model: sizes / margins / paddings / borders / ...  */
  width: 200px;
  padding: 5px;
  border: 1px solid #ddd;


/* typographic: font / aligns / text styles / ... /
font-size: 14px;
line-height: 20px;


/* visual: colors / shadows / gradients / ... */
  background: #f5f5f5;
  color: #333;
  -webkit-transition: color 1s;
     -moz-transition: color 1s;
          transition: color 1s;
}

注释规范 ​

文件顶部注释 ​

css
/*
 * @description:  中文说明
 * @author: name
 * @update: name (2013-04-13 18:32)
*/

模块注释 ​

css
/* module: module1 by  张三  */

单行注释与多行注释 ​

单行注释可以写在单独一行，也可以写在行尾，注释中的每一行长度不超过 40 个汉字，或者 80 个英文字符。

css
/*
 * this is comment line 1.
 * this is comment line 2.
*/

多行注释必须写在单独行内

特殊注释 ​

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

css
/* TODO: xxxx by name 2013-04-13 18:32 */
/* BUGFIX: xxxx by name 2012-04-13 18:32 */

区块注释 ​

对一个代码区块注释（可选），将样式语句分区块并在新行中对其注释。

css
/* Header */
/* Footer */
/* Gallery */

常用的 CSS 命名规则 ​

1 ​

头：header 内容：content/container 尾：footer 导航：nav 侧栏：sidebar 栏目：column 页面外围控制整体布局宽度：wrapper 左右中：left right center 登录条：loginbar 标志：logo 广告：banner 页面主体：main 热点：hot 新闻：news 下载：download 子导航：subnav 菜单：menu 子菜单：submenu 搜索：search 友情链接：friendlink 页脚：footer 版权：copyright 滚动：scroll 内容：content 标签页：tab 文章列表：list 提示信息：msg 小技巧：tips 栏目标题：title 加入：joinus 指南：guild 服务：service 注册：regsiter 状态：status 投票：vote 合作伙伴：partner

页面结构 ​

容器: container 页头：header 内容：content/container 页面主体：main 页尾：footer 导航：nav 侧栏：sidebar 栏目：column 页面外围控制整体布局宽度：wrapper 左右中：left right center

导航 ​

导航：nav 主导航：mainbav 子导航：subnav 顶导航：topnav 边导航：sidebar 左导航：leftsidebar 右导航：rightsidebar 菜单：menu 子菜单：submenu 标题: title 摘要: summary

功能 ​

标志：logo 广告：banner 登陆：login 登录条：loginbar 注册：regsiter 搜索：search 功能区：shop 标题：title 加入：joinus 状态：status 按钮：btn 滚动：scroll 标签页：tab 文章列表：list 提示信息：msg 当前的: current 小技巧：tips 图标: icon 注释：note 指南：guild 服务：service 热点：hot 新闻：news 下载：download 投票：vote 合作伙伴：partner 友情链接：link 版权：copyright

其他 ​

page、wrap、layout、header(head)、footer(foot、ft)、 content(cont)、menu、nav、main、subMain、sidebar(side)、logo、banner、 title(tit)、pop、icon、note、btn、txt、window(win)、tips

Copyright © 2020-2025 KIT