HTML5 编码规范

HTML 风格指南与编码规范

为什么编码规范很重要

一致的编码风格能让 HTML 更易于阅读、理解和维护，尤其是在团队协作时。尽管 HTML5 语法灵活，但建立规范可以提高代码质量并减少错误。

遵循最佳实践还有助于确保与各种工具（如代码检查工具（linters）、代码格式化工具（formatters）和无障碍检查工具（accessibility checkers））的兼容性，并使你的代码面向未来。

使用正确的文档类型 (DOCTYPE)

始终以 DOCTYPE 声明开始你的 HTML 文档。对于 HTML5，它很简单，并能确保浏览器以标准模式渲染页面：

<!DOCTYPE html>

这应该是 HTML 文件中的第一行。

使用小写元素和属性名称

虽然 HTML5 允许大小写混合，但广泛接受的规范是所有元素（element）和属性（attribute）名称都使用小写。

一致性：避免混淆。
可读性：小写通常被认为更清晰。
兼容性：与 CSS 和 JavaScript 等相关语言以及 XML 等更严格的格式保持一致。
工具支持：许多开发工具期望使用小写。

关闭所有非空（Non-Void）HTML 元素

虽然 HTML5 允许省略某些元素（如 <p>、<li>）的闭合标签，但强烈建议明确地关闭所有非空元素（non-void elements）。

清晰度：使文档结构更清晰。
可维护性：减少嵌套错误的风险。
工具支持：使代码编辑器和验证工具更容易正确解析。

一致处理空（Void）HTML 元素

空元素（Void elements）不能包含内容，也不需要闭合标签（例如，<meta>、<img>、<br>、<hr>、<input>）。

HTML5 语法允许省略尾部的斜杠：

<meta charset="utf-8">
<img src="logo.png" alt="Logo">

XHTML 要求尾部带斜杠：

<meta charset="utf-8" />
<img src="logo.png" alt="Logo" />

最佳实践：选择一种风格（空元素是否带尾部斜杠）并在整个项目中保持一致。许多团队在现代 HTML5 中省略了斜杠。

始终引用属性值

在某些条件下（例如，不包含空格或特殊字符），HTML5 允许省略属性值周围的引号。然而，最佳实践是始终使用引号将属性值括起来。

安全性：防止值包含空格或特殊字符时出错。
可读性：清晰地区分属性值。
一致性：避免混用风格。

图像属性 (`src`、`alt`、`width`、`height`)

始终为 <img> 元素提供 src（源 URL）和 alt（替代文本）属性。

alt：对无障碍访问（屏幕阅读器）和 SEO 至关重要。描述图像的内容或功能。
src：指定图像文件的路径。

包含 width 和 height 属性有助于浏览器预留空间，防止图像加载时引起布局偏移。

<img src="images/product.jpg" alt="A red t-shirt with a logo" width="300" height="400">

注意：虽然 width 和 height 属性设置了固有尺寸，但应使用 CSS 进行响应式图像样式设置（例如，max-width: 100%; height: auto;）。

代码格式化（缩进和换行）

一致的缩进和逻辑换行显著提高可读性。

缩进：使用空格（通常是 2 或 4 个）来表示嵌套层级。避免使用 Tab 键或混用 Tab 和空格。
行长：保持行长适中（例如，小于 80-100 个字符），以避免水平滚动。
空行：谨慎使用空行来分隔逻辑代码块。

可读性示例：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Formatted Example</title>
</head>
<body>

  <header>
    <h1>Page Title</h1>
  </header>

  <main>
    <article>
      <h2>Article Heading</h2>
      <p>
        This is a paragraph with well-formatted text,
        making it easy to read and understand the structure.
      </p>
    </article>
  </main>

</body>
</html>

像 Prettier 或编辑器集成这样的工具可以自动格式化你的代码。

省略可选标签 (`<html>`、`<head>`、`<body>`)

虽然 HTML5 规范在技术上允许省略 <html>、<head> 和 <body> 标签，但强烈建议包含它们。

清晰度：明确定义了文档结构。
无障碍访问：<html> 标签是使用 lang 属性（例如，<html lang="en">）声明页面语言的标准位置。
兼容性：一些旧版浏览器或工具在缺少这些标签时可能会出现问题。
一致性：这是开发者所教导和期望的标准结构。

推荐结构：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Page Title</title>
  <!-- Other meta tags, links, scripts -->
</head>
<body>
  <!-- Page content -->
</body>
</html>

必备的 Meta 数据

在 <head> 部分包含必备的 meta 信息：

字符编码：尽早声明 UTF-8 以确保字符正确显示。<meta charset="UTF-8">
标题：<title> 元素是必需的，对浏览器标签页、书签和 SEO 至关重要。使其具有描述性。<title>Meaningful Page Title</title>
视口（用于响应式设计）：对于控制移动设备上的布局至关重要。<meta name="viewport" content="width=device-width, initial-scale=1.0">

<head> 示例：

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>HTML Style Guide</title>
  <link rel="stylesheet" href="styles.css">
</head>

HTML 注释

使用注释（）来解释代码段、记录复杂逻辑或临时禁用代码。保持注释简洁且相关。

<!-- 主导航菜单 -->
<nav>
  <!-- ... -->
</nav>

<!-- TODO: 稍后重构此部分 -->
<!-- <div class="old-component">...</div> -->

链接 CSS 和 JavaScript

在 <head> 标签内使用 <link> 标签链接外部 CSS 文件。type="text/css" 属性不再是必需的。

<link rel="stylesheet" href="css/main.css">

使用 <script> 标签链接外部 JavaScript 文件。通常将脚本放在闭合的 </body> 标签之前可以提高感知的加载速度。type="text/javascript" 属性也是不必要的。

<script src="js/app.js"></script>
<!-- 使用 async 或 defer 属性来优化加载 -->
<script src="js/analytics.js" async></script>

使用 async 或 defer 属性来控制脚本的加载和执行，而不会阻塞页面渲染。

文件命名规范

使用小写的文件名和目录名。单词之间使用连字符（-）分隔，而不是下划线（_）或空格。

一致性：更易于管理文件。
服务器兼容性：避免在区分大小写的文件系统（如 Linux/Unix）上出现问题。
URL 可读性：带有连字符的名称通常更适合 URL。

推荐：about-us.html、contact-form.css、image-gallery.js

避免：AboutUs.html、contact_form.css、Image Gallery.js

使用标准文件扩展名：HTML 文件使用 .html，CSS 使用 .css，JavaScript 使用 .js。