htmx

HTMX

将此技能用于 HTMX 的实现与集成。涵盖 htmx 2.x（当前稳定版）和 htmx 4.x（测试版）。参考文件中使用了 [htmx 4]、[htmx 4 change] 和 [htmx 4 removed] 提示标记。只需阅读任务所需的参考文件。

快速开始

1. 确定任务所属的领域（属性、请求、交换、事件、模式）。
2. 打开 references/ 中对应的文件。
3. 使用 HTML 优先、超媒体驱动的模式进行实现。
4. 验证服务端响应返回的是 HTML 片段，而不是 JSON。

最简示例 — 一个通过 GET 加载内容的按钮：

<button hx-get="/contacts" hx-target="#results" hx-swap="innerHTML">
    Load Contacts
</button>
<div id="results"></div>

服务端端点（/contacts）必须返回 HTML 片段，而不是 JSON：

<ul>
    <li>Alice</li>
    <li>Bob</li>
</ul>

默认交换方式是 innerHTML — 响应会替换目标元素的子元素。使用 hx-swap="outerHTML" 可替换目标元素本身。

关键规则

1. HTML 响应 - HTMX 需要服务端返回 HTML 响应，而不是 JSON
2. 属性继承 - （v2）大多数属性会继承到子元素；使用 hx-disinherit 或 unset 可停止继承。（v4）继承是显式的 — 使用 :inherited 后缀启用继承。两个版本中都不继承： hx-trigger、hx-on*、hx-swap-oob、hx-preserve、hx-history-elt、hx-validate
3. 默认交换方式为 innerHTML - 始终确认所需的交换方式
4. 自动包含表单值 - 非 GET 请求会自动包含最近外层表单的值
5. 渐进增强 - 使用 hx-boost="true" — 页面必须在没有 JS 的情况下正常工作
6. 转义用户内容 - 在服务端转义所有用户提供的内容，防止 XSS。使用 hx-disable 包裹渲染用户生成内容的区域，防止 HTMX 处理注入的属性
7. CSS 生命周期类 - HTMX 会在请求期间添加和移除 CSS 类 — 可用于过渡效果和指示器
8. 支持 data- 前缀 - 所有 hx-* 属性也可以写为 data-hx-*，以符合 HTML 验证要求
9. 使用 HTTP 286 停止轮询 - 服务端返回状态码 286，即可停止 every 或 load delay 轮询。停止轮询时始终使用 286，不要使用有条件的客户端逻辑
10. 错误响应交换 - （v2）默认不会交换非 2xx 响应 — 添加 htmx:beforeSwap 监听器以启用。（v4）默认会交换所有响应，204/304 除外 — 使用 hx-status 按状态码控制
11. 通过 HX-Trigger 响应头解耦 - 使用 HX-Trigger 响应头触发客户端事件，避免在服务端响应中硬编码 DOM 元素 ID
12. 在服务端检测 HTMX 请求 - 检查 HX-Request 请求头，为 HTMX 请求提供 HTML 片段，为直接浏览器请求提供完整页面。设置 Vary: HX-Request 以支持缓存

参考索引

• 所有 hx-* 属性、值和修饰符：references/attributes.md
• 触发器、请求头、参数、CSRF、缓存、CORS：references/requests.md
• 交换方式、目标、OOB 交换、形态变换、视图过渡：references/swapping.md
• 事件、JS API、配置、扩展、调试：references/events-api.md
• 常见 UI 模式和示例：references/patterns.md
• 官方扩展（WS、SSE、Idiomorph、response-targets、head-support、preload、hx-live、hx-prompt）：references/extensions.md
• 易错点、陷阱和实用指南：references/gotchas.md
• 跨文件索引和路由：references/REFERENCE.md

任务路由

• 为元素添加 HTMX 行为 -> references/attributes.md
• 配置请求的触发方式和时机 -> references/requests.md
• 控制响应的呈现位置和方式 -> references/swapping.md
• 处理事件、JS 互操作或配置 -> references/events-api.md
• 构建常见 UI 模式（搜索、无限滚动、模态框等） -> references/patterns.md
• 使用 WebSockets、SSE、形态转换、预加载、响应定向或 head 合并 -> references/extensions.md
• 避免常见问题，处理无障碍、错误以及架构决策 -> references/gotchas.md
• 处理跨领域问题或架构问题 -> 先查看 references/REFERENCE.md，再查看特定领域的文件