前端开发规范 - HTML 代码规范

altq 1/13/2022 note

前端开发规范系列 - HTML 代码规范

Markup Validation Service (opens new window)

# DOCTYPE 声明

一个 DOCTYPE 必须包含以下部分，并严格按照顺序出现：

A string that is an ASCII case-insensitive match for the string “<!DOCTYPE”.

One or more space characters.

A string that is an ASCII case-insensitive match for the string “html”.

Optionally, a DOCTYPE legacy string or an obsolete permitted DOCTYPE string (defined below).

Zero or more space characters.

A “>” (U+003E) character.

一个 ASCII 字符串 “<!DOCTYPE” ，大小写不敏感
一个或多个空白字符
一个 ASCII 字符串”html”，大小写不敏感
一个可选的历史遗留的 DOCTYPE 字符串 （DOCTYPE legacy string），或者一个可选的已过时但被允许的 DOCTYPE 字符串 （obsolete permitted DOCTYPE string） 字符串
一个或多个空白字符
一个编码为 U+003E 的字符 “>”

# 团队约定

HTML 文件必须加上 DOCTYPE 声明，并统一使用 HTML5 的文档声明：

<!DOCTYPE html>

# 更多关于 DOCTYPE 声明 HTML 版本

从 Web 诞生早期至今，已经发展出多个 HTML 版本：

版本	年份
HTML	1991
HTML+	1993
HTML 2.0	1995
HTML 3.2	1997
HTML 4.01	1999
XHTML 1.0	2000
HTML5	2012
XHTML5	2013

# 常用的声明

# HTML5

<!DOCTYPE html>

DOCTYPE 标签是一种标准通用标记语言的文档类型声明，它的目的是要告诉标准通用标记语言解析器，它应该使用什么样的文- 档类型定义（DTD）来解析文档。
使用文档声明类型的作用是为了防止开启浏览器的怪异模式。
没有 DOCTYPE 文档类型声明会开启浏览器的怪异模式，浏览器会按照自己的解析方式渲染页面，在不同的浏览器下面会有不同的样式。
如果你的页面添加了<!DOCTYP>那么，那么就等同于开启了标准模式。浏览器会按照 W3C 标准解析渲染页面。

# HTML 4.01

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">

1
2

# XHTML 1.0

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

1
2

# 页面语言 LANG

Lang 属性的取值应该遵循互联网工程任务组–IETF（The Internet Engineering Task Force）制定的关于语言标签的文档 BCP 47 - Tags for Identifying Languages (opens new window)

# 团队约定

推荐使用属性值 zh-CN 属性值更多地区语言参考：

zh-CN 中文 (简体, 大陆)
zh-SG 中文 (简体, 新加坡)
zh-HK 中文 (繁体, 香港)
zh-MO 中文 (繁体, 澳门)
zh-TW 中文 (繁体, 台湾)

1
2
3
4
5

# 已废弃不推荐使用的 Languages Tags

以下写法已于 2009 年废弃，请勿使用（cmn、wuu、yue、gan 等已由 2005 年的 extlang 升级到 2009 年的 language）：

zh-cmn, zh-cmn-Hans, zh-cmn-Hant, zh-wuu, zh-yue, zh-gan

以下写法已于 2009 年废弃，不推荐使用：

zh-Hans, zh-Hans-CN, zh-Hans-SG, zh-Hans-HK, zh-Hans-MO, zh-Hans-TW,
zh-Hant, zh-Hant-CN, zh-Hant-SG, zh-Hant-HK, zh-Hant-MO, zh-Hant-TW

1
2

更多已废弃 Languages Tags 参考 IANA Language Subtag Registry (opens new window) 里面的 “Type: redundant“”

# 更多关于 Languages Tags ：

W3C Language tags in HTML and XML (opens new window)

网页头部的声明应该是用 lang=”zh” 还是 lang=”zh-cn”？ (opens new window)

# CHARSET

Because the character sets in ISO-8859 was limited in size, and not compatible in multilingual environments, the Unicode Consortium developed the Unicode Standard.

The Unicode Standard covers (almost) all the characters, punctuations, and symbols in the world.

Unicode enables processing, storage, and transport of text independent of platform and language.

The default character encoding in HTML-5 is UTF-8.

因为 ISO-8859 中字符集大小是有限的，且在多语言环境中不兼容，所以 Unicode 联盟开发了 Unicode 标准。

Unicode 标准覆盖了（几乎）所有的字符、标点符号和符号。

Unicode 使文本的处理、存储和运输，独立于平台和语言。

HTML-5 中默认的字符编码是 UTF-8

参阅 HTML Unicode (UTF-8) Reference (opens new window)

# 团队约定

一般情况下统一使用 UTF-8 编码

<meta charset="UTF-8">

由于历史原因，有些业务可能会使用 “GBK” 编码

<meta charset="GBK">

请尽量统一写成标准的 “UTF-8”，不要写成 “utf-8” 或 “utf8” 或 “UTF8”。根据 IETF 对 UTF-8 的定义 (opens new window)，其编码标准的写法是 “UTF-8”；而 UTF8 或 utf8 的写法只是出现在某些编程系统中，如 .NET framework 的类 System.Text.Encoding 中的一个属性名就叫 UTF8。

GBK：Application of IANA Charset Registration for GBK (opens new window)

Charset ：character-encoding-declaration (opens new window)

# 元素及标签闭合

HTML 元素共有以下 6 种：

空元素：area、base、br、col、command、embed、hr、img、input、keygen、link、meta、param、source、track、wbr
原始文本元素：script、style
RCDATA 元素：textarea、title
外来元素：来自 MathML 命名空间和 SVG 命名空间的元素。
常规元素：其他 HTML 允许的元素都称为常规元素。
模板元素：template。

元素标签的闭合应遵循以下原则：

Tags are used to delimit the start and end of elements in the markup. Raw text, escapable raw text, and normal elements have a start tag to indicate where they begin, and an end tag to indicate where they end. The start and end tags of certain normal elements can be omitted, as described below in the section on optional tags. Those that cannot be omitted must not be omitted. Void elements only have a start tag; end tags must not be specified for void elements. Foreign elements must either have a start tag and an end tag, or a start tag that is marked as self-closing, in which case they must not have an end tag.

原始文本元素、RCDATA 元素以及常规元素都有一个开始标签来表示开始，一个结束标签来表示结束。
某些元素的开始和结束标签是可以省略的 (opens new window)，如果规定标签不能被省略，那么就绝对不能省略它。
空元素只有一个开始标签，且不能为空元素设置结束标签。
外来元素可以有一个开始标签和配对的结束标签，或者只有一个自闭合的开始标签，且后者情况下该元素不能有结束标签。

# 团队约定

为了能让浏览器更好的解析代码以及能让代码具有更好的可读性，有如下约定：

所有具有开始标签和结束标签的元素都要写上起止标签，某些允许省略开始标签或和束标签的元素亦都要写上。
空元素标签都不加 “/” 字符, 即不要在自闭合（self-closing）元素的尾部添加斜线 — HTML5 规范 (opens new window) 中明确说明斜线是可忽略的。
标签必须合法且闭合、嵌套正确，标签名需小写
标签语法无错误，需要符合语义化
标签的自定义属性以 data-开头，如：
除非有特定的功能、组件要求等，禁止随意使用 id 来定义元素样式

推荐：

<div>
    <h1>我是h1标题</h1>
    <p>我是一段文字，我有始有终，浏览器能正确解析</p>
</div>

<br>

1
2
3
4
5
6

不推荐：

<div>
    <h1>我是h1标题</h1>
    <p>我是一段文字，我有始无终，浏览器亦能正确解析
</div>

<br/>

1
2
3
4
5
6

更多关于元素及标签关闭：Elements (opens new window)

# 语义化

我们一直都在说语义化编程，语义化编程，但是在代码中很少有人完全使用正确的元素。使用语义化标签也是有理由 SEO 的。

语义化是指：根据元素其被创造出来时的初始意义来使用它。意思就是用正确的标签干正确的事，而不是只有div和span。

不推荐：

<b>My page title</b>
<div class="top-navigation">
  <div class="nav-item"><a href="#home">Home</a></div>
  <div class="nav-item"><a href="#news">News</a></div>
  <div class="nav-item"><a href="#about">About</a></div>
</div>

<div class="news-page">
  <div class="page-section news">
    <div class="title">All news articles</div>
    <div class="news-article">
      <h2>Bad article</h2>
      <div class="intro">Introduction sub-title</div>
      <div class="content">This is a very bad example for HTML semantics</div>
      <div class="article-side-notes">I think I'm more on the side and should not receive the main credits</div>
      <div class="article-foot-notes">
        This article was created by David <div class="time">2014-01-01 00:00</div>
      </div>
    </div>

    <div class="section-footer">
      Related sections: Events, Public holidays
    </div>
  </div>
</div>

<div class="page-footer">
  Copyright 2014
</div>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 书写风格

# HTML 代码大小写

HTML 标签名、类名、标签属性和大部分属性值统一用小写

推荐：

<div class="demo"></div>

不推荐：

<div class="DEMO"></div>

<DIV CLASS="DEMO"></DIV>

1
2
3

HTML 文本、CDATA、JavaScript、meta 标签某些属性等内容可大小写混合

<!-- 优先使用 IE 最新版本和 Chrome Frame -->
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>

<!-- HTML文本内容 -->
<h1>I AM WHAT I AM </h1>

<!-- JavaScript 内容 -->
<script type="text/javascript">
	var demoName = 'demoName';
	...
</script>

<!-- CDATA 内容 -->
<script type="text/javascript"><![CDATA[
...
]]></script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# alt 标签不为空

<img>标签的 alt 属性指定了替代文本，用于在图像无法显示或者用户禁用图像显示时，代替图像显示在浏览器中的内容。假设由于下列原因用户无法查看图像，alt 属性可以为图像提供替代的信息：

网速太慢
src 属性中的错误
浏览器禁用图像
用户使用的是屏幕阅读器

从 SEO 角度考虑，浏览器的爬虫爬不到图片的内容，所以我们要有文字告诉爬虫图片的内容

# 结构、表现、行为三者分离 (不做强制限定)

尽量在文档和模板中只包含结构性的 HTML；而将所有表现代码，移入样式表中；将所有动作行为，移入脚本之中。在此之外，为使得它们之间的联系尽可能的小，在文档和模板中也尽量少地引入样式和脚本文件。建议：

不使用超过一到两张样式表
不使用超过一到两个脚本（学会用合并脚本）
不使用行内样式（<style>.no-good {}</style>）
不在元素上使用 style 属性（<hr style="border-top: 5px solid black">）
不使用行内脚本（<script>alert('no good')</script>）
不使用表象元素（i.e. <b>, <u>, <center>, <font>, <b>）
不使用表象 class 名（i.e. red, left, center）

# HTML 只关注内容

HTML 只显示展示内容信息
不要引入一些特定的 HTML 结构来解决一些视觉设计问题
不要将 img 元素当做专门用来做视觉设计的元素
样式上的问题应该使用 css 解决

不推荐：

<!-- We should not introduce an additional element just to solve a design problem  -->
<span class="text-box">
  <span class="square"></span>
  See the square next to me?
</span>
css 代码:
.text-box > .square {
  display: inline-block;
  width: 1rem;
  height: 1rem;
  background-color: red;
}

1
2
3
4
5
6
7
8
9
10
11
12

# 类型属性

不需要为 CSS、JS 指定类型属性，HTML5 中默认已包含

推荐：

<link rel="stylesheet" href="" >
<script src=""></script>

1
2

不推荐：

<link rel="stylesheet" type="text/css" href="" >
<script type="text/javascript" src="" ></script>

1
2

# 元素属性

元素属性值使用双引号语法
元素属性值可以写上的都写上

推荐：

<input type="text">

<input type="radio" name="name" checked="checked" >

1
2
3

不推荐：

<input type=text>
<input type='text'>

<input type="radio" name="name" checked >

1
2
3
4

更多关于元素属性：Attributes (opens new window)

# 减少标签的数量

编写 HTML 代码时，尽量避免多余的父元素。很多时候，这需要迭代和重构来实现。请看下面的案例：

<!-- Not so great -->
<span class="avatar">
  <img src="..." />
</span>

<!-- Better -->
<img class="avatar" src="..." />

1
2
3
4
5
6
7

# JavaScript 生成的标签 (不做强制限定)

通过 JavaScript 生成的标签让内容变得不易查找、编辑，并且降低性能。能避免时尽量避免。

# 特殊字符引用

In certain cases described in other sections, text may be mixed with character references. These can be used to escape characters that couldn’t otherwise legally be included in text.

文本可以和字符引用混合出现。这种方法可以用来转义在文本中不能合法出现的字符。

在 HTML 中不能使用小于号 “<” 和大于号 “>”特殊字符，浏览器会将它们作为标签解析，若要正确显示，在 HTML 源代码中使用字符实体

推荐：

<a href="#">more&gt;&gt;</a>

不推荐：

<a href="#">more>></a>

更多关于符号引用：Character references (opens new window)

# 代码缩进

用两个空格来代替制表符（tab） -- 这是唯一能保证在所有环境下获得一致展现的方法。
嵌套元素应当缩进一次（即两个空格）。

<div class="uihc">
  <a href="#"></a>
</div>

1
2
3

# 纯数字输入框

使用 type="tel" 而不是 type="number"

<input type="tel">

# 代码嵌套

元素嵌套规范，每个块状元素独立一行，内联元素可选

推荐：

<div>
    <h1></h1>
    <p></p>
</div>
<p><span></span><span></span></p>

1
2
3
4
5

不推荐：

<div>
    <h1></h1><p></p>
</div>
<p>
    <span></span>
    <span></span>
</p>

1
2
3
4
5
6
7

段落元素与标题元素只能嵌套内联元素

推荐：

<h1><span></span></h1>
<p><span></span><span></span></p>

1
2

不推荐：

<h1><div></div></h1>
<p><div></div><div></div></p>

1
2

# HTML5 spec links

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css" />

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

1
2
3
4
5
6
7
8
9
10

# 实用为王

尽量遵循 HTML 标准和语义，但是不要以牺牲实用性为代价。任何时候都要尽量使用最少的标签并保持最小的复杂度。

# 属性顺序

HTML 属性应当按照以下给出的顺序依次排列，确保代码的易读性。

class
id, name
data-*
src, for, type, href, value
title, alt
role, aria-*

class 用于标识高度可复用组件，因此应该排在首位。id 用于标识具体组件，应当谨慎使用（例如，页面内的书签），因此排在第二位。

<a class="..." id="..." data-toggle="modal" href="#"> Example link </a>

<input class="form-control" type="text" />

<img src="..." alt="..." />

1
2
3
4
5

# 布尔（boolean）型属性

布尔型属性可以在声明时不赋值。XHTML 规范要求为其赋值，但是 HTML5 规范不需要。

更多信息请参考 WhatWG section on boolean attributes (opens new window)：

元素的布尔型属性如果有值，就是 true，如果没有值，就是 false。

如果一定要为其赋值的话，请参考 WhatWG 规范：

如果属性存在，其值必须是空字符串或 [...] 属性的规范名称，并且不要在首尾添加空白符。

简单来说，就是不用赋值。

<input type="text" disabled />

<input type="checkbox" value="1" checked />

<select>
  <option value="1" selected>1</option>
</select>

1
2
3
4
5
6
7

# 脚本加载

说到 js 和 css 的位置，大家应该都知道 js 放在下面，css 放在上面。

但是，如果你的项目只需要兼容 ie10+或者只是在移动端访问，那么可以使用 HTML5 的新属性 async，将脚本文件放在<head>内
兼容老旧浏览器(IE9-)时：
脚本引用写在 body 结束标签之前，并带上 async 属性。这虽然在老旧浏览器中不会异步加载脚本，但它只阻塞了 body 结束标签之前的 DOM 解析，这就大大降低了其阻塞影响。
而在现代浏览器中：
脚本将在 DOM 解析器发现 body 尾部的 script 标签才进行加载，此时加载属于异步加载，不会阻塞 CSSOM（但其执行仍发生在 CSSOM 之后）。

综上所述，所有浏览器中推荐:

<html>
  <head>
    <link rel="stylesheet" href="main.css">
  </head>
  <body>
    <!-- body goes here -->

    <script src="main.js" async></script>
  </body>
</html>

1
2
3
4
5
6
7
8
9
10

只兼容现代浏览器推荐:

<html>
  <head>
    <link rel="stylesheet" href="main.css">
    <script src="main.js" async></script>
  </head>
  <body>
    <!-- body goes here -->
  </body>
</html>

1
2
3
4
5
6
7
8
9

# 文件模版

HTML 模版指的是团队使用的初始化 HTML 文件，里面会根据不同平台而采用不一样的设置，一般主要不同的设置就是 mata 标签的设置，以下是 PC 和移动端的 HTML 模版。

# HTML5 标准模版

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>HTML5标准模版</title>
</head>
<body>

</body>
</html>

1
2
3
4
5
6
7
8
9
10

# 团队约定

# 移动端

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, shrink-to-fit=no" >
<meta name="format-detection" content="telephone=no" >
<title>移动端HTML模版</title>

<!-- S DNS预解析 -->
<link rel="dns-prefetch" href="">
<!-- E DNS预解析 -->

<!-- S 线上样式页面片，开发请直接取消注释引用 -->
<!-- #include virtual="" -->
<!-- E 线上样式页面片 -->

<!-- S 本地调试，根据开发模式选择调试方式，请开发删除 -->
<link rel="stylesheet" href="css/index.css" >
<!-- /本地调试方式 -->

<link rel="stylesheet" href="http://srcPath/index.css" >
<!-- /开发机调试方式 -->
<!-- E 本地调试 -->

</head>
<body>

</body>
</html>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# PC 端

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="keywords" content="your keywords">
<meta name="description" content="your description">
<meta name="author" content="author,email address">
<meta name="robots" content="index,follow">
<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
<meta name="renderer" content="ie-stand">
<title>PC端HTML模版</title>

<!-- S DNS预解析 -->
<link rel="dns-prefetch" href="">
<!-- E DNS预解析 -->

<!-- S 线上样式页面片，开发请直接取消注释引用 -->
<!-- #include virtual="" -->
<!-- E 线上样式页面片 -->

<!-- S 本地调试，根据开发模式选择调试方式，请开发删除 -->
<link rel="stylesheet" href="css/index.css" >
<!-- /本地调试方式 -->

<link rel="stylesheet" href="http://srcPath/index.css" >
<!-- /开发机调试方式 -->
<!-- E 本地调试 -->

</head>
<body>

</body>
</html>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 团队约定

# 修改方法

打开 vs code ->点击文件->首选项->用户片段；搜索 html.json；以下是一个标准的 HTML 模板。

"cdichtml": {
        "prefix": "cdichtml",
        "body": [
            "<!DOCTYPE html>",
			"<html lang=\"ch-ZN\">",
			"",
			"<head>",
			"    <meta charset=\"UTF-8\">",
			"    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0\">",
			"    <meta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\">",
			"    <title>Document</title>",
			"</head>",
			"",
			"<body>",
			"   ",
			"</body>",
			"",
			"</html>",
        ],
        "description": "Log output to console"
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Viewport Meta Tag

# 通用类设置

<meta name="viewport" content="width=device-width, initial-scale=1.0,
maximum-scale=1.0, user-scalable=no">

1
2

width – viewport 的宽度
height – viewport 的高度
initial-scale – 初始的缩放比例
minimum-scale – 允许用户缩放到的最小比例
maximum-scale – 允许用户缩放到的最大比例
user-scalable – 是否允许用户缩放

# Safari on iOS viewport

The width of the viewport in pixels. The default is 980. The range is from 200 to 10,000.

The minimum-scale and maximum-scale properties also affect the behavior when changing orientations. The range of these property values is from >0 to 10.0. The default value for minimum-scale is 0.25 and maximum-scale is 5.0

user-scalable – The default is yes. Setting user-scalable to no also prevents a webpage from scrolling when entering text in an input field.

默认宽度是 980px，范围从 200px 到 10000px
initial-scale 缩放比例范围值是从 >0 到 10 之间
minimum-scale 默认值是 0.25
maximum-scale 默认值是 5
user-scalable – 默认值是 yes，设置 no 还可以在文本框输入文本的时候阻止页面滚动

更多关于 Safari on iOS viewport 的设置:

Configuring the Viewport (opens new window) Safari HTML Reference (opens new window)

Altq's blog