Back to Details

html

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML Development Guidelines

HTML开发指南

Core Principles

核心原则

Write semantic HTML to improve accessibility and SEO
Use appropriate elements for their intended purpose
Ensure proper document structure and hierarchy
Prioritize accessibility by using ARIA roles and attributes when needed

编写语义化HTML以提升无障碍性和SEO
使用符合预期用途的恰当元素
确保正确的文档结构和层级
在需要时使用ARIA角色和属性，优先保障无障碍性

Semantic Elements

语义化元素

Document Structure

文档结构

Use
```
<header>
```
for introductory content and navigation
Use
```
<main>
```
for the primary content (one per page)
Use
```
<footer>
```
for footer content
Use
```
<nav>
```
for navigation sections
Use
```
<aside>
```
for tangentially related content

使用
```
<header>
```
承载介绍性内容和导航
使用
```
<main>
```
承载主要内容（每页一个）
使用
```
<footer>
```
承载页脚内容
使用
```
<nav>
```
承载导航区域
使用
```
<aside>
```
承载次要相关内容

Content Sections

内容区块

Use
```
<article>
```
for self-contained, distributable content
Use
```
<section>
```
for thematic grouping of content
Use appropriate heading hierarchy (
```
<h1>
```
through
```
<h6>
```
)
Only one
```
<h1>
```
per page, representing the main topic

使用
```
<article>
```
承载独立可分发的内容
使用
```
<section>
```
承载主题性内容分组
使用恰当的标题层级（
```
<h1>
```
至
```
<h6>
```
）
每页仅保留一个
```
<h1>
```
，代表页面核心主题

Text Content

文本内容

Use
```
<p>
```
for paragraphs
Use
```
<ul>
```
,
```
<ol>
```
,
```
<dl>
```
for lists appropriately
Use
```
<blockquote>
```
for quotations
Use
```
<figure>
```
and
```
<figcaption>
```
for illustrations

使用
```
<p>
```
承载段落
根据需求恰当使用
```
<ul>
```
、
```
<ol>
```
、
```
<dl>
```
列表
使用
```
<blockquote>
```
承载引用内容
使用
```
<figure>
```
和
```
<figcaption>
```
承载插图及说明

Interactive Elements

交互元素

Buttons and Links

按钮与链接

Use
```
<button>
```
for clickable actions that don't navigate
Use
```
<a>
```
for links that navigate to URLs
Always include
```
href
```
attribute on links
Never use
```
<div>
```
or
```
<span>
```
for clickable elements

使用
```
<button>
```
实现不涉及页面跳转的可点击操作
使用
```
<a>
```
实现跳转到URL的链接
链接必须包含
```
href
```
属性
切勿使用
```
<div>
```
或
```
<span>
```
实现可点击元素

Forms

表单

Use
```
<form>
```
with proper
```
action
```
and
```
method
```
attributes
Associate labels with inputs using
```
for
```
attribute
Use appropriate input types (
```
email
```
,
```
tel
```
,
```
number
```
, etc.)
Group related inputs with
```
<fieldset>
```
and
```
<legend>
```
Include validation attributes (
```
required
```
,
```
pattern
```
,
```
min
```
,
```
max
```
)

使用带有正确
```
action
```
和
```
method
```
属性的
```
<form>
```
通过
```
for
```
属性将标签与输入框关联
使用恰当的输入类型（
```
email
```
、
```
tel
```
、
```
number
```
等）
使用
```
<fieldset>
```
和
```
<legend>
```
对相关输入框进行分组
包含验证属性（
```
required
```
、
```
pattern
```
、
```
min
```
、
```
max
```
）

Media Elements

媒体元素

Images

图片

Always include
```
alt
```
attribute for images
Use descriptive alt text for informational images
Use empty
```
alt=""
```
for decorative images
Use
```
srcset
```
and
```
sizes
```
for responsive images
Include
```
width
```
and
```
height
```
to prevent layout shift

图片必须包含
```
alt
```
属性
为信息类图片添加描述性替代文本
为装饰性图片设置空值
```
alt=""
```
使用
```
srcset
```
和
```
sizes
```
实现响应式图片
包含
```
width
```
和
```
height
```
属性以避免布局偏移

Video and Audio

视频与音频

Provide captions and transcripts
Include multiple source formats for compatibility
Use
```
poster
```
attribute for video thumbnails
Consider autoplay impact on user experience

提供字幕和文字转录
包含多种源格式以保证兼容性
为视频设置
```
poster
```
属性指定缩略图
考虑自动播放对用户体验的影响

Accessibility (ARIA)

无障碍访问（ARIA）

When to Use ARIA

ARIA的使用场景

Use ARIA when native HTML semantics are insufficient
Prefer native HTML elements over ARIA when possible
Ensure ARIA attributes match actual element behavior

当原生HTML语义不足以满足需求时使用ARIA
优先使用原生HTML元素而非ARIA
确保ARIA属性与元素实际行为匹配

Common ARIA Attributes

常用ARIA属性

```
aria-label
```
for accessible names
```
aria-describedby
```
for additional descriptions
```
aria-hidden
```
for decorative elements
```
aria-expanded
```
for expandable sections
```
aria-live
```
for dynamic content updates

```
aria-label
```
：设置无障碍名称
```
aria-describedby
```
：添加额外描述
```
aria-hidden
```
：标记装饰性元素
```
aria-expanded
```
：标记可展开区域
```
aria-live
```
：标记动态内容更新区域

Landmarks

地标角色

Use landmark roles to define page regions
Ensure all content is within a landmark
Use
```
role="main"
```
,
```
role="navigation"
```
, etc., only when semantic elements aren't available

使用地标角色定义页面区域
确保所有内容都包含在地标区域内
仅当语义化元素不可用时，才使用
```
role="main"
```
、
```
role="navigation"
```
等地标角色

Best Practices

最佳实践

Document Meta

文档元数据

Include proper
```
<!DOCTYPE html>
```
declaration
Set language attribute on
```
<html>
```
element
Include viewport meta tag for responsive design
Use appropriate meta tags for SEO

包含正确的
```
<!DOCTYPE html>
```
声明
在
```
<html>
```
元素上设置语言属性
添加视口元标签以实现响应式设计
使用恰当的元标签优化SEO

Code Quality

代码质量

Validate HTML using W3C validator
Maintain consistent indentation
Close all tags properly (including self-closing)
Use lowercase for element names and attributes

使用W3C验证工具校验HTML
保持一致的缩进格式
正确闭合所有标签（包括自闭合标签）
元素名称和属性使用小写

Deprecated Elements

已废弃元素

Avoid
```
<font>
```
,
```
<center>
```
,
```
<b>
```
,
```
<i>
```
for styling
Use CSS for visual presentation
Use
```
<strong>
```
and
```
<em>
```
for semantic emphasis

避免使用
```
<font>
```
、
```
<center>
```
、
```
<b>
```
、
```
<i>
```
进行样式设置
使用CSS实现视觉呈现
使用
```
<strong>
```
和
```
<em>
```
实现语义化强调

HTMX Integration

HTMX集成

When using HTMX for interactivity:

Use
```
hx-get
```
,
```
hx-post
```
attributes for server requests
Leverage
```
hx-target
```
to specify update targets
Use
```
hx-swap
```
to control how content is inserted
Implement
```
hx-confirm
```
for critical actions
Use
```
hx-push-url
```
for URL updates without full refresh

使用HTMX实现交互时：

使用
```
hx-get
```
、
```
hx-post
```
属性发起服务器请求
利用
```
hx-target
```
指定内容更新目标
使用
```
hx-swap
```
控制内容插入方式
为关键操作实现
```
hx-confirm
```
确认机制
使用
```
hx-push-url
```
实现无全页刷新的URL更新

Bootstrap Integration

Bootstrap集成

When using Bootstrap:

Leverage Bootstrap's grid system for layouts
Use Bootstrap components with proper markup structure
Include necessary ARIA attributes with components
Use Bootstrap's utility classes for spacing and typography
Minimize custom CSS by using Bootstrap classes

使用Bootstrap时：

利用Bootstrap栅格系统构建布局
按照正确的标记结构使用Bootstrap组件
为组件添加必要的ARIA属性
使用Bootstrap工具类实现间距和排版
优先使用Bootstrap类以减少自定义CSS的编写

Performance

性能优化

Minimize DOM depth and complexity
Load scripts with
```
defer
```
or
```
async
```
when appropriate
Use
```
loading="lazy"
```
for below-fold images
Preload critical resources with
```
<link rel="preload">
```

最小化DOM深度和复杂度
适时使用
```
defer
```
或
```
async
```
加载脚本
为首屏外图片设置
```
loading="lazy"
```
实现懒加载
使用
```
<link rel="preload">
```
预加载关键资源