EnlightenCode

HTML 编码规范 ​

文档 ​

文档类型 ​

  • **【强制】**使用 HTML5 DOCTYPE。 在 HTML 文档的开头使用 <!DOCTYPE html> 来声明文档的 HTML 版本。
html
<!-- bad - 非 HTML 5 DOCTYPE -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html></html>

<!-- good -->
<!DOCTYPE html>
<html></html>

语言 ​

  • **【推荐】**指定 html 标签上的 lang 属性。
html
<html lang="zh-CN">
 <!-- ... -->
</html>

元数据 ​

  • **【推荐】**使用 UTF-8 字符编码
html
<head>
 <meta charset="utf-8" />
</head>
  • **【推荐】**页面提供给移动设备使用时，需要设置 viewport 设置 viewport-fit 设置为“cover”来兼容刘海屏
html
<meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />

资源加载 ​

  • **【推荐】**引入 CSS 和 JavaScript 时无需指定 type。 根据 HTML5 规范，引入 CSS 和 JavaScript 时通常不需要指明 type，因为 text/css (opens new window)和 text/javascript (opens new window)分别是他们的默认值。
html
<!-- bad -->
<link type="text/css" rel="stylesheet" href="example.css" />
<style type="text/css">
 /* ... */
</style>
<script type="text/javascript" src="example.js"></script>

<!-- good -->
<link rel="stylesheet" href="example.css" />
<style>
 /* ... */
</style>
<script src="example.js"></script>
  • **【推荐】**在 head 标签内引入 CSS，在 body 结束标签前引入 JS。 在<body></body>中指定外部样式表和嵌入式样式块可能会导致页面的重排和重绘，对页面的渲染造成影响。因此，一般情况下，CSS 应在 <head></head> 标签里引入

除了基础库等必须要在 DOM 加载之前运行的 JavaScript 脚本，其他都在靠近 body 结束标签前引入，以防止出现页面渲染的阻塞

html
<!-- bad -->
<!DOCTYPE html>
<html>
 <head>
  <script src="mod-a.js"></script>
  <script src="jquery.js"></script>
 </head>
 <body>
  <style>
   .mod-example {
    padding-left: 15px;
   }
  </style>
 </body>
</html>

<!-- good -->
<!DOCTYPE html>
<html>
 <head>
  <style>
   .mod-example {
    padding-left: 15px;
   }
  </style>
 </head>
 <body>
  ...
  <script src="path/to/my/script.js"></script>
 </body>
</html>
  • **【推荐】**外部资源的引用地址跟随页面协议，省略协议部分
html
<link rel="stylesheet" href="//g.cdn.com/lib/style/index-min.css" />
  • **【推荐】**使用 preload 预加载关键资源
html
<link rel="preload" href="style.css" as="style" />
<link rel="preload" href="main.js" as="script" />
  • **【推荐】**使用 dns-prefetch 和 preconnect 处理 DNS 解析延迟问题，提高网页加载性能
html
<link rel="preconnect" href="https://fonts.googleapis.com/" crossorigin />
<link rel="dns-prefetch" href="https://fonts.googleapis.com/" />

页面标题 ​

  • **【强制】**页面需要指定 title 标签，有且仅有 1 个。
html
<head>
 <meta charset="utf-8" />
 <title>XXX</title>
</head>

编码 ​

缩进 ​

  • **【推荐】**统一使用 2 个空格缩进，不要使用 4 个空格或 tab 缩进

注释 ​

  • **【强制】**在 HTML 注释代码中，不允许出现任何敏感信息

  • **【推荐】**单行注释，需在注释内容和注释符之间需留有一个空格，以增强可读性

  • **【推荐】**多行注释，注释符单独占一行，注释内容 2 个空格缩进。

标签 ​

  • **【强制】**标签名统一使用小写。

  • **【推荐】**不要省略自闭合标签结尾处的斜线，且斜线前需留有一个空格。

html
<!-- bad -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<img src="images/foo.png" alt="foo">

<!-- good -->
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<img src="images/foo.png" alt="foo" />

属性 ​

  • **【强制】**属性值使用双引号，不要使用单引号。
html
<!-- bad -->
<link rel='stylesheet' href='example.css' />

<!-- good -->
<link rel="stylesheet" href="example.css" />
  • **【推荐】**不要为 Boolean 属性添加取值
html
<!-- bad -->
<input type="text" disabled="disabled" />
<input type="checkbox" value="1" checked="checked" />
<select>
 <option value="1" selected="selected">1</option>
</select>

<!-- good -->
<input type="text" disabled />
<input type="checkbox" value="1" checked />
<select>
 <option value="1" selected>1</option>
</select>
  • **【推荐】**自定义属性的命名：以 data- 为前缀
html
<!-- bad -->
<a modal="toggle" href="#">Example link</a>

<!-- good -->
<a data-modal="toggle" href="#">Example link</a>

语义化 ​

  • **【参考】**尽量根据语义使用 HTML 标签
html
<!-- bad -->
<div class="list">
 <div class="list-item">1</div>
 <div class="list-item">2</div>
 <div class="list-item">3</div>
</div>

<!-- good -->
<ul class="list">
 <li class="list-item">1</li>
 <li class="list-item">2</li>
 <li class="list-item">3</li>
</ul>

可访问性 ​

  • **【参考】**注意 HTML 的可访问性（Accessibility）
html
<!-- bad - 缺少 alt 属性，无法被无障碍阅读器识别 -->
<img src="hello.jpg" />

<!-- good -->
<img src="hello.jpg" alt="Welcome to visit!" />

<!-- good - 图片无需被无障碍阅读器识别时 -->
<img src="logo.jpg" alt="" />

<!-- good - 图片无需被无障碍阅读器识别时 -->
<img src="logo.jpg" role="presentation" />

脚手架模板 ​

html
<!DOCTYPE html>
<html lang="zh-CN">
 <head>
  <meta charset="utf-8" />
  <meta name="description" content="印客学院 - 一千个职业梦想的赞助商" />
  <meta name="keyword" content="印客学院" />
  <meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
  <title>XXX</title>
  <link rel="stylesheet" href="example.css" />
 </head>
 <body>
  <div id="container"></div>
  <script src="example.js"></script>
 </body>
</html>