html

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML Style Guide

HTML风格指南

This skill applies Google's HTML style guide conventions to ensure clean, semantic, and maintainable HTML code.

本技能应用Google的HTML风格指南规范，确保HTML代码简洁、语义化且可维护。

Core Principles

核心原则

Document Structure

文档结构

Always use HTML5 doctype and UTF-8 encoding:

html

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

始终使用HTML5 doctype和UTF-8编码：

html

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

Semantic HTML

语义化HTML

Use elements according to their purpose:

Headings (
```
h1
```
-
```
h6
```
) for hierarchical structure
```
p
```
for paragraphs
```
a
```
for links and navigation
```
button
```
for interactive actions
Avoid
```
div
```
for clickable elements

html

<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- Recommended -->
<a href="recommendations/">All recommendations</a>

根据元素用途使用对应标签：

标题（
```
h1
```
-
```
h6
```
）用于搭建层级结构
```
p
```
用于段落
```
a
```
用于链接和导航
```
button
```
用于交互操作
避免使用
```
div
```
作为可点击元素

html

<!-- 不推荐 -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- 推荐 -->
<a href="recommendations/">All recommendations</a>

Separation of Concerns

关注点分离

Keep structure (HTML), presentation (CSS), and behavior (JavaScript) strictly separated:

No inline styles (
```
style
```
attribute)
No inline event handlers (
```
onclick
```
, etc.)
Link minimal CSS and JavaScript files

html

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

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

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

不使用行内样式（
```
style
```
属性）
不使用行内事件处理器（
```
onclick
```
等）
仅引入必要的CSS和JavaScript文件

html

<!-- 不推荐 -->
<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 Style Rules

HTML样式规则

Valid HTML

有效HTML

Use valid HTML code tested with W3C HTML validator
Ensure proper opening and closing tags
Nest elements correctly

html

<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.

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

使用经W3C HTML validator测试的有效HTML代码
确保开闭标签正确
元素嵌套层级正确

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>

Protocol

协议

Always use HTTPS for embedded resources:

html

<!-- Not recommended -->
<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>

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

嵌入式资源始终使用HTTPS：

html

<!-- 不推荐 -->
<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>

Multimedia

多媒体

Provide alternative content for accessibility:

Use meaningful
```
alt
```
text for images
Provide transcripts/captions for video/audio
Use
```
alt=""
```
for purely decorative images

html

<!-- Not recommended -->
<img src="spreadsheet.png">

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

为无障碍访问提供替代内容：

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

html

<!-- 不推荐 -->
<img src="spreadsheet.png">

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

Entity References

实体引用

Do not use entity references (except for special HTML characters):

Exception:
```
<
```
,
```
&
```
, and invisible characters
Use UTF-8 encoding directly

html

<!-- Not recommended -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.

<!-- Recommended -->
The currency symbol for the Euro is "€".

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

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

html

<!-- 不推荐 -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.

<!-- 推荐 -->
The currency symbol for the Euro is "€".

Optional Tags

可选标签

Consider omitting optional tags for file size optimization:

html

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

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

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

html

<!-- 不推荐 -->
<!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.

Type Attributes

类型属性

Omit

type

attributes for CSS and JavaScript (HTML5 defaults):

html

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

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

CSS和JavaScript省略

type

属性（HTML5默认支持）：

html

<!-- 不推荐 -->
<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 Attributes

ID属性

Minimize use of

id

attributes:

Prefer
```
class
```
for styling
Prefer
```
data-*
```
for scripting
When required, always include hyphen (e.g.,
```
user-profile
```
not
```
userProfile
```
)
Prevents global
```
window
```
namespace pollution

html

<!-- Not recommended: window.userProfile conflicts -->
<div id="userProfile"></div>

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

尽量少用

id

属性：

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

html

<!-- 不推荐：window.userProfile命名冲突 -->
<div id="userProfile"></div>

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

Formatting Rules

格式规则

Indentation

缩进

Indent by 2 spaces (no tabs):

html

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

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

html

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

Capitalization

大小写

Use only lowercase for:

Element names
Attributes
Attribute values (except text/CDATA)

html

<!-- Not recommended -->
<A HREF="/">Home</A>

<!-- Recommended -->
<img src="google.png" alt="Google">

所有内容仅使用小写：

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

html

<!-- 不推荐 -->
<A HREF="/">Home</A>

<!-- 推荐 -->
<img src="google.png" alt="Google">

Whitespace

空格

Remove trailing whitespace:

html

<!-- Not recommended -->
<p>What?_

<!-- Recommended -->
<p>Yes please.

删除尾随空格：

html

<!-- 不推荐 -->
<p>What?_

<!-- 推荐 -->
<p>Yes please.

Block Elements

块级元素

Use new line for every block, list, or table element:

html

<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>

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

html

<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>

Line Wrapping

换行

Break long lines for readability (optional but recommended):

html

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

长内容换行以提升可读性（可选但推荐）：

html

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

Quotation Marks

引号

Use double quotes for attribute values:

html

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

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

属性值使用双引号：

html

<!-- 不推荐 -->
<a class='maia-button maia-button-secondary'>Sign in</a>

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

Code Quality Guidelines

代码质量指南

Comments

注释

Use comments to explain complex sections:

html

<!-- TODO: Remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

使用注释解释复杂代码段：

html

<!-- TODO: 移除可选标签 -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

Action Items

待办项

Mark todos with

TODO:

keyword:

html

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

使用

TODO:

关键词标记待办事项：

html

{# TODO: 重新调整居中逻辑 #}
<center>Test</center>

Quick Reference

快速参考

Rule	Convention
Doctype	`<!doctype html>`
Encoding	UTF-8 with `<meta charset="utf-8">`
Protocol	HTTPS for all resources
Indentation	2 spaces
Case	Lowercase only
Quotes	Double quotes ( `"` )
Type attributes	Omit for CSS/JS
Semantic elements	Use elements for their purpose
Accessibility	Always provide `alt` for images
IDs	Minimize use, include hyphens

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

Additional Resources

额外资源

references/html-detailed.md
- Comprehensive HTML patterns and edge cases
W3C HTML Validator
Google HTML/CSS Style Guide

references/html-detailed.md
- 全面的HTML编写模式和边缘场景处理
W3C HTML验证器
Google HTML/CSS风格指南

Summary

总结

Write HTML that is:

Valid: Passes W3C validation
Semantic: Uses elements for their intended purpose
Accessible: Includes alt text and proper structure
Separated: No inline styles or scripts
Consistent: Follows formatting conventions
Lowercase: All element/attribute names
Secure: HTTPS for all resources

编写的HTML需要满足：

有效：通过W3C验证
语义化：按元素预期用途使用
可访问：包含alt文本和正确结构
关注点分离：无行内样式或脚本
一致性：遵循格式规范
全小写：所有元素/属性名称使用小写
安全：所有资源使用HTTPS