html

HTML 开发指南

核心原则

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

语义元素

文档结构

• 使用 <header> 放置介绍性内容和导航
• 使用 <main> 放置主要内容（每页一个）
• 使用 <footer> 放置页脚内容
• 使用 <nav> 放置导航区域
• 使用 <aside> 放置相关性较弱的内容

内容分区

• 使用 <article> 放置独立且可分发的内容
• 使用 <section> 对内容进行主题分组
• 使用恰当的标题层级（<h1> 至 <h6>）
• 每页仅使用一个 <h1>，用于表示主题

文本内容

• 使用 <p> 表示段落
• 根据需要使用 <ul>、<ol>、<dl> 创建列表
• 使用 <blockquote> 表示引用
• 使用 <figure> 和 <figcaption> 展示插图

交互元素

按钮和链接

• 使用 <button> 执行不会跳转的可点击操作
• 使用 <a> 创建跳转到 URL 的链接
• 链接始终包含 href 属性
• 切勿使用 <div> 或 <span> 作为可点击元素

表单

• 使用 <form>，并设置恰当的 action 和 method 属性
• 使用 for 属性将标签与输入框关联
• 使用恰当的输入类型（email、tel、number 等）
• 使用 <fieldset> 和 <legend> 对相关输入框进行分组
• 添加验证属性（required、pattern、min、max）

媒体元素

图像

• 图像始终包含 alt 属性
• 为信息性图像编写描述性替代文本
• 装饰性图像使用空的 alt=""
• 响应式图像使用 srcset 和 sizes
• 设置 width 和 height，避免布局偏移

视频和音频

• 提供字幕和文字稿
• 包含多种源格式，以确保兼容性
• 使用 poster 属性设置视频缩略图
• 考虑自动播放对用户体验的影响

无障碍性（ARIA）

何时使用 ARIA

• 原生 HTML 语义不足时使用 ARIA
• 尽可能优先使用原生 HTML 元素，而非 ARIA
• 确保 ARIA 属性与元素的实际行为一致

常见 ARIA 属性

• aria-label 用于设置无障碍名称
• aria-describedby 用于提供补充说明
• aria-hidden 用于装饰性元素
• aria-expanded 用于可展开区域
• aria-live 用于动态内容更新

地标

• 使用地标角色定义页面区域
• 确保所有内容都位于某个地标内
• 仅在没有可用语义元素时使用 role="main"、role="navigation" 等

最佳实践

文档元数据

• 添加正确的 <!DOCTYPE html> 声明
• 在 <html> 元素上设置语言属性
• 添加 viewport 元标签以支持响应式设计
• 使用恰当的 SEO 元标签

代码质量

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

已弃用元素

• 避免使用 <font>、<center>、<b>、<i> 设置样式
• 使用 CSS 控制视觉呈现
• 使用 <strong> 和 <em> 表示语义强调

HTMX 集成

使用 HTMX 实现交互时：

• 使用 hx-get、hx-post 属性发送服务端请求
• 使用 hx-target 指定更新目标
• 使用 hx-swap 控制内容的插入方式
• 对关键操作使用 hx-confirm
• 使用 hx-push-url 更新 URL，无需完整刷新页面

Bootstrap 集成

使用 Bootstrap 时：

• 使用 Bootstrap 网格系统进行布局
• 使用 Bootstrap 组件，并采用正确的标记结构
• 为组件添加必要的 ARIA 属性
• 使用 Bootstrap 实用类设置间距和排版
• 尽量使用 Bootstrap 类，减少自定义 CSS

性能

• 尽量减少 DOM 深度和复杂性
• 在适当情况下，使用 defer 或 async 加载脚本
• 对首屏以下的图片使用 loading="lazy"
• 使用 <link rel="preload"> 预加载关键资源