html

HTML 样式指南

此技能采用 Google HTML 样式指南的规范，确保 HTML 代码简洁、语义明确且易于维护。

核心原则

文档结构

始终使用 HTML5 文档类型声明和 UTF-8 编码：

<!doctype html>
<meta charset="utf-8">
<title>Page Title</title>

语义化 HTML

根据元素的用途使用它们：

• 使用标题（h1-h6）构建层级结构
• 使用 p 表示段落
• 使用 a 创建链接和导航
• 使用 button 处理交互操作
• 避免将 div 用作可点击元素

<div onclick="goToRecommendations();">All recommendations</div>


<a href="recommendations/">All recommendations</a>

关注点分离

严格分离结构（HTML）、表现（CSS）和行为（JavaScript）：

• 不使用内联样式（style 属性）
• 不使用内联事件处理器（onclick 等）
• 链接精简的 CSS 和 JavaScript 文件

<h1 style="font-size: 1em;">HTML sucks</h1>
<center>Centered content</center>


<!doctype html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>

HTML 样式规则

有效的 HTML

• 使用 W3C HTML validator 测试 HTML 代码的有效性
• 确保开始标签和结束标签正确
• 正确嵌套元素

<title>Test</title>
<article>This is only a test.


<!doctype html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

协议

嵌入资源时始终使用 HTTPS：

<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>


<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

多媒体

提供无障碍替代内容：

• 为图片使用有意义的 alt 文本
• 为视频/音频提供文字稿/字幕
• 纯装饰性图片使用 alt=""

<img src="spreadsheet.png">


<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
<img src="decorative-border.png" alt="">

字符实体引用

不要使用字符实体引用（特殊 HTML 字符除外）：

• 例外：<、& 和不可见字符
• 直接使用 UTF-8 编码

The currency symbol for the Euro is “&eur;”.


The currency symbol for the Euro is "€".

可选标签

可考虑省略可选标签以优化文件大小：

<!doctype html>
<html>
  <head>
    <title>Spending money, spending bytes</title>
  </head>
  <body>
    <p>Sic.</p>
  </body>
</html>


<!doctype html>
<title>Saving money, saving bytes</title>
<p>Qed.

类型属性

省略 CSS 和 JavaScript 的 type 属性（HTML5 默认值）：

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


<link rel="stylesheet" href="styles.css">
<script src="script.js"></script>

ID 属性

尽量减少 id 属性的使用：

• 样式设置优先使用 class
• 脚本优先使用 data-*
• 必须使用时，始终包含连字符（例如，使用 user-profile，而不是 userProfile）
• 避免污染全局 window 命名空间

<div id="userProfile"></div>


<div aria-describedby="user-profile">
  <div id="user-profile"></div>
</div>

格式规则

缩进

使用 2 个空格缩进（不使用制表符）：

<ul>
  <li>Fantastic
  <li>Great
</ul>

大小写

以下内容全部使用小写：

• 元素名称
• 属性
• 属性值（文本/CDATA 除外）

<A HREF="/">Home</A>


<img src="google.png" alt="Google">

空白字符

删除行尾空白：

<p>What?_


<p>Yes please.

块级元素

每个块级元素、列表或表格元素单独占一行：

<blockquote>
  <p><em>Space</em>, the final frontier.</p>
</blockquote>

<ul>
  <li>Moe
  <li>Larry
  <li>Curly
</ul>

<table>
  <thead>
    <tr>
      <th scope="col">Income
      <th scope="col">Taxes
  <tbody>
    <tr>
      <td>$ 5.00
      <td>$ 4.50
</table>

自动换行

为提高可读性，将长行拆分为多行（可选，但建议这样做）：

<button
  mat-icon-button
  color="primary"
  class="menu-button"
  (click)="openMenu()"
>
  <mat-icon>menu</mat-icon>
</button>

引号

属性值使用双引号：

<a class='maia-button maia-button-secondary'>Sign in</a>


<a class="maia-button maia-button-secondary">Sign in</a>

代码质量指南

注释

使用注释说明复杂部分：

<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

待办事项

使用 TODO: 关键字标记待办事项：

{# TODO: Revisit centering. #}
<center>Test</center>

快速参考

规则	规范
文档类型声明	<!doctype html>
编码	UTF-8，使用 <meta charset="utf-8">
协议	所有资源均使用 HTTPS
缩进	2 个空格
大小写	仅使用小写
引号	双引号（"）
类型属性	CSS/JS 中省略
语义化元素	根据用途使用元素
无障碍	始终为图片提供 alt
ID	尽量少用，并包含连字符

更多资源

• references/html-detailed.md - 全面的 HTML 模式和边缘情况
• W3C HTML Validator
• Google HTML/CSS Style Guide

总结

编写的 HTML 应当：

• 有效：通过 W3C 验证
• 语义明确：使用符合预期用途的元素
• 无障碍：包含替代文本并采用恰当的结构
• 分离：不使用内联样式或脚本
• 一致：遵循格式规范
• 小写：所有元素/属性名称均使用小写
• 安全：所有资源均使用 HTTPS