HTMX 核心属性
使用 htmx 时最常见的属性。
| 属性 | 描述 |
|---|---|
| hx-get | 向指定 URL发出 GET 请求 |
| hx-post | 向指定 URL发出 POST 请求 |
| hx-on* | 使用元素上的内联脚本处理事件 |
| hx-push-url | 将 URL 推送到浏览器地址栏以创建历史记录 |
| hx-select | 从响应中选择要交换的内容 |
| hx-select-oob | 从响应中选择要交换的内容，而不是目标（带外） |
| hx-swap | 控制内容如何交换（outerHTML, beforeend, afterend, ... ） |
| hx-swap-oob | 标记要从响应中交换的元素（带外） |
| hx-target | 指定要交换的目标元素 |
| hx-trigger | 指定触发请求的事件 |
| hx-vals | 添加要随请求一起提交的值（JSON 格式） |
HTMX 附加属性
所有其他属性均在 htmx 中可用。
| 属性 | 描述 |
|---|---|
| hx-boost | 为链接和表单添加渐进式增强功能 |
| hx-confirm | 在发出请求之前显示 confirm() 对话框 |
| hx-delete | 向指定 URL发出 DELETE 请求 |
| hx-disable | 禁用给定节点及其子节点的 htmx 处理 |
| hx-disabled-elt | 在请求进行过程中将 disabled 属性添加到指定元素 |
| hx-disinherit | 控制和禁用子节点的自动属性继承 |
| hx-encoding | 更改请求编码类型 |
| hx-ext | 用于此元素的扩展 |
| hx-headers | 添加到将随请求一起提交的 HTTP 头中 |
| hx-history | 防止敏感数据被保存到历史缓存中 |
| hx-history-elt | 历史导航期间要进行快照和恢复的元素 |
| hx-include | 在请求中包含其他数据 |
| hx-indicator | 请求期间放置 htmx-request 类的元素 |
| hx-inherit | 控制并启用子节点的自动属性继承（如果默认情况下已禁用） |
| hx-params | 过滤随请求提交的参数 |
| hx-patch | 向指定 URL发出 PATCH 请求 |
| hx-preserve | 指定在请求之间保持不变的元素 |
| hx-prompt | 在提交请求之前显示 prompt() |
| hx-put | 向指定 URL发出 PUT 请求 |
| hx-replace-url | 替换浏览器地址栏中的 URL |
| hx-request | 配置请求的各个方面 |
| hx-sync | 定义不同元素发出的请求如何同步 |
| hx-validate | 强制元素在请求之前进行自我验证 |
| hx-vars | 将值动态地添加到与请求一起提交的参数中（已弃用，请使用 hx-vals ） |
HTMX CSS 类
| 类 | 描述 |
|---|---|
| htmx-added | 在交换新内容之前应用它，在交换完成后删除。 |
| htmx-indicator | htmx-request 动态生成的类，当存在某个类时，它将切换可见性（不透明度：1） |
| htmx-request | hx-indicator 在请求正在进行时应用于元素或指定的元素 |
| htmx-settling | 内容交换后应用于目标，结算后移除。持续时间可通过 hx-swap 修改。 |
| htmx-swapping | 在交换任何内容之前应用于目标，在交换后删除。持续时间可以通过 hx-swap 修改。 |
HTMX 请求头
| HTTP头 | 描述 |
|---|---|
| HX-Boosted | 表示请求是通过使用 hx-boost 的元素进行的 |
| HX-Current-URL | 浏览器的当前 URL |
| HX-History-Restore-Request | 如果请求是在本地历史缓存未命中后进行历史恢复，则为“true” |
| HX-Prompt | 用户对 hx-prompt 的响应 |
| HX-Request | 总是为 true |
| HX-Target | 目标元素的 id (如果存在) |
| HX-Trigger-Name | 触发元素的name（如果存在） |
| HX-Trigger | 触发元素的id（如果存在） |
HTMX 响应头
| HTTP头 | 描述 |
|---|---|
| HX-Location | 允许你进行非完整页面重新加载的客户端重定向 |
| HX-Push-Url | 将新的 URL 推送到历史堆栈中 |
| HX-Redirect | 可用于将客户端重定向到新位置 |
| HX-Refresh | 如果设置为“true”，客户端将完全刷新页面 |
| HX-Replace-Url | 替换地址栏中的当前 URL |
| HX-Reswap | 允许你指定如何交换响应。请参阅 hx-swap了解可能的值 |
| HX-Retarget | CSS 选择器，将内容更新的目标更新为页面上的不同元素 |
| HX-Reselect | 一个 CSS 选择器，允许你选择要交换响应的哪一部分。覆盖触发元素上现有的 hx-select |
| HX-Trigger | 允许你触发客户端事件 |
| HX-Trigger-After-Settle | 允许你在结算步骤后触发客户端事件 |
| HX-Trigger-After-Swap | 允许你在交换步骤后触发客户端事件 |
HTMX 事件
| 事件 | 描述 |
|---|---|
| htmx:abort | 发送该事件给元素以中止请求 |
| htmx:afterOnLoad | 在 AJAX 请求完成处理成功响应后触发 |
| htmx:afterProcessNode | htmx 初始化节点后触发 |
| htmx:afterRequest | AJAX 请求完成后触发 |
| htmx:afterSettle | 在 DOM 稳定后触发 |
| htmx:afterSwap | 在换入新内容后触发 |
| htmx:beforeCleanupElement | 在 htmx 禁用元素或将其从 DOM 中移除之前触发 |
| htmx:beforeOnLoad | 在任何响应处理发生之前触发 |
| htmx:beforeProcessNode | 在 htmx 初始化节点之前触发 |
| htmx:beforeRequest | 在发出 AJAX 请求之前触发 |
| htmx:beforeSwap | 在交换完成之前触发，允许你配置交换 |
| htmx:beforeSend | 在发送 ajax 请求之前触发 |
| htmx:beforeTransition | 在视图转换交换发生之前触发 |
| htmx:configRequest | 在请求之前触发，允许你自定义参数、标头 |
| htmx:confirm | 在元素上发生触发器后触发，允许你取消（或延迟）发出 AJAX 请求 |
| htmx:historyCacheError | 缓存写入过程中发生错误时触发 |
| htmx:historyCacheMiss | 在历史子系统中发生缓存未命中时触发 |
| htmx:historyCacheMissError | 远程检索失败时触发 |
| htmx:historyCacheMissLoad | 远程检索成功时触发 |
| htmx:historyRestore | 当 htmx 处理历史记录恢复操作时触发 |
| htmx:beforeHistorySave | 在内容保存到历史缓存之前触发 |
| htmx:load | 当新内容添加到 DOM 时触发 |
| htmx:noSSESourceError | 当元素在其触发器中引用 SSE 事件但尚未定义父 SSE 源时触发 |
| htmx:onLoadError | 在 htmx 中的 onLoad 处理期间发生异常时触发 |
| htmx:oobAfterSwap | 在带外元素被换入后触发 |
| htmx:oobBeforeSwap | 在带外元素交换完成之前触发，允许你配置交换 |
| htmx:oobErrorNoTarget | 当带外元素在当前 DOM 中没有匹配的 ID 时触发 |
| htmx:prompt | 在提示显示后触发 |
| htmx:pushedIntoHistory | 当 URL 被推送到历史记录中时触发 |
| htmx:responseError | 当发生HTTP 响应错误（非响应代码200或响应代码300）时触发 |
| htmx:sendAbort | 请求中止时触发 |
| htmx:sendError | 当网络错误阻止 HTTP 请求发生时触发 |
| htmx:sseError | 当 SSE 源发生错误时触发 |
| htmx:sseOpen | 当 SSE 源打开时触发 |
| htmx:swapError | 交换阶段发生错误时触发 |
| htmx:targetError | 当指定无效目标时触发 |
| htmx:timeout | 当请求超时时触发 |
| htmx:validation:validate | 在元素验证之前触发 |
| htmx:validation:failed | 当元素验证失败时触发 |
| htmx:validation:halted | 当请求由于验证错误而停止时触发 |
| htmx:xhr:abort | 当 ajax 请求中止时触发 |
| htmx:xhr:loadend | 当 ajax 请求结束时触发 |
| htmx:xhr:loadstart | 当 ajax 请求开始时触发 |
| htmx:xhr:progress | 在支持进度事件的 ajax 请求期间定期触发 |
HTMX JavaScript API
| 方法 | 描述 |
|---|---|
| htmx.addClass() | 为给定元素添加一个类 |
| htmx.ajax() | 发出 htmx 样式的 ajax 请求 |
| htmx.closest() | 查找与选择器匹配的给定元素的最近父元素 |
| htmx.config | 保存当前 htmx 配置对象的属性 |
| htmx.createEventSource | 拥有为 htmx 创建 SSE EventSource 对象的功能的属性 |
| htmx.createWebSocket | 保存为 htmx 创建 WebSocket 对象的函数的属性 |
| htmx.defineExtension() | 定义 htmx扩展名 |
| htmx.find() | 查找与选择器匹配的单个元素 |
| htmx.findAll() htmx.findAll(elt, selector) |
查找与给定选择器匹配的所有元素 |
| htmx.logAll() | 安装一个记录器，用于记录所有 htmx 事件 |
| htmx.logger | 设置为当前记录器的属性（默认为null） |
| htmx.off() | 从给定元素中删除事件监听 |
| htmx.on() | 在给定元素上创建一个事件监听器，并返回它 |
| htmx.onLoad() | htmx:load为事件添加回调处理程序 |
| htmx.parseInterval() | 将间隔声明解析为毫秒值 |
| htmx.process() | 处理给定元素及其子元素，连接任何 htmx 行为 |
| htmx.remove() | 删除给定元素 |
| htmx.removeClass() | 从给定元素中删除一个类 |
| htmx.removeExtension() | 删除 htmx 扩展 |
| htmx.swap() | 执行 HTML 内容的交换（和稳定） |
| htmx.takeClass() | 从其他元素中为给定元素选取一个类 |
| htmx.toggleClass() | 切换给定元素的类 |
| htmx.trigger() | 触发元素上的事件 |
| htmx.values() | 返回与给定元素关联的输入值 |
HTMX 配置选项
Htmx 有一些配置选项，可以通过编程或声明方式访问。它们列在下面：
| 配置变量 | 信息 |
|---|---|
| htmx.config.historyEnabled | 默认为true，实际上只用于测试 |
| htmx.config.historyCacheSize | 默认为 10 |
| htmx.config.refreshOnHistoryMiss | 默认为false，如果设置为true，将在历史记录未命中时发出整页刷新，而不是使用 AJAX 请求 |
| htmx.config.defaultSwapStyle | 默认为innerHTML |
| htmx.config.defaultSwapDelay | 默认为 0 |
| htmx.config.defaultSettleDelay | 默认为 20 |
| htmx.config.includeIndicatorStyles | 默认为true（确定是否加载指示器样式） |
| htmx.config.indicatorClass | 默认为 htmx-indicator |
| htmx.config.requestClass | 默认为 htmx-request |
| htmx.config.addedClass | 默认为 htmx-added |
| htmx.config.settlingClass | 默认为 htmx-settling |
| htmx.config.swappingClass | 默认为 htmx-swapping |
| htmx.config.allowEval | 默认为true，可用于禁用 htmx 对 eval 的某些功能（例如触发过滤器）的使用 |
| htmx.config.allowScriptTags | 默认为true，确定 htmx 是否处理在新内容中找到的脚本标签 |
| htmx.config.inlineScriptNonce | 默认为''，意味着不会向内联脚本添加任何随机数 |
| htmx.config.inlineStyleNonce | 默认为''，意味着不会将任何随机数添加到内联样式中 |
| htmx.config.attributesToSettle | 默认为["class", "style", "width", "height"]，在结算阶段要结算的属性 |
| htmx.config.wsReconnectDelay | 默认为 full-jitter |
| htmx.config.wsBinaryType | 默认为blob，通过 WebSocket 连接接收的二进制数据类型 |
| htmx.config.disableSelector | 默认为[hx-disable], [data-hx-disable]，htmx 将不会处理具有此属性的元素或其父元素 |
| htmx.config.disableInheritance | 默认为 false。如果设置为 true 则完全禁用属性的继承，并且可以使用 hx-inherittrue 属性明确指定继承。 |
| htmx.config.withCredentials | 默认为false，允许使用诸如 cookies、授权头或 TLS 客户端证书之类的凭证进行跨站点访问控制请求 |
| htmx.config.timeout | 默认为 0，即请求在自动终止前可以花费的毫秒数 |
| htmx.config.scrollBehavior | 默认为“instant”，即 hx-swap 使用 show 修饰符时的滚动行为。允许的值为instant（滚动应在一次跳转中立即发生）、smooth（滚动应流畅地进行动画）和（滚动行为由 scroll-behaviorauto 的计算值决定）。 |
| htmx.config.defaultFocusScroll | 如果焦点元素应该滚动到视图中，则默认为 false ，并且可以使用焦点滚动交换修改器进行覆盖。 |
| htmx.config.getCacheBusterParam | 默认为 false，如果设置为 true，htmx 将以格式将目标元素附加到 GET 请求中 的 org.htmx.cache-buster=targetElementId 格式 |
| htmx.config.globalViewTransitions | 如果设置为true，htmx 将在交换新内容时使用 View Transition API。 |
| htmx.config.methodsThatUseUrlParams | 默认为["get", "delete"]，htmx 将通过在 URL 中编码其参数来格式化使用这些方法的请求，而不是请求正文 |
| htmx.config.selfRequestsOnly | 默认为true，是否仅允许对与当前文档相同的域进行 AJAX 请求 |
| htmx.config.ignoreTitle | 默认为false，如果设置为 true，则在新内容中发现 title 标签时不会更新文档的标题 |
| htmx.config.scrollIntoViewOnBoost | 默认为true，无论增强元素的目标是否滚动到视口中。如果 hx-target 在增强元素上省略，则目标默认为body，且页面滚动到顶部。 |
| htmx.config.triggerSpecsCache | 默认为null，用于存储评估的触发器规范的缓存，以更多的内存使用为代价来提高解析性能。你可以定义一个简单的对象来使用永不清除的缓存，或者使用代理对象实现你自己的系统 |
| htmx.config.responseHandling | 可以在此处配置响应状态代码的默认响应处理行为，以交换或错误 |
| htmx.config.allowNestedOobSwaps | 默认为true，是否处理嵌套在主响应元素中的元素的 OOB 交换。请参阅嵌套 OOB 交换。 |
你可以直接在 javascript 中设置它们，也可以使用meta标签：
<meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>
HTMX 扩展
htmx 支持扩展，以增强其提供的核心超媒体基础结构。扩展机制减轻了核心库添加新功能的压力，使其能够专注于其主要目的，即推广超媒体控件。
如果你有兴趣为 htmx 创建扩展，请参阅 构建 htmx 扩展。
htmx 扩展分为两类：
- 核心扩展 - 由 htmx 团队支持
- 社区扩展 — 得到更广泛社区的支持
核心扩展
| 扩展名称 | 描述 |
|---|---|
| head-support | 提供对 htmx 请求中 head 标签信息（样式等）合并的支持 |
| htmx-1-compat | 将 htmx 2 的大部分行为更改回滚到 htmx 1 的默认设置。 |
| idiomorph | 提供基于htmx 团队创建的 idiomorph 变形库 morph 的交换策略。 |
| preload | 此扩展程序允许你在用户请求 HTML 片段之前将其加载到浏览器的缓存中，以便用户几乎可以立即加载其他页面。 |
| response-targets | 此扩展允许你在收到不同的 HTTP 响应代码时指定要交换的不同目标元素。 |
| sse | 直接从 HTML 提供对服务器发送事件的支持。 |
| ws | 直接从 HTML 提供与 Web Sockets 服务器的双向通信 |
社区扩展
| 扩展名称 | 描述 |
|---|---|
| ajax-header | 为 htmx 发出的所有请求添加 X-Requested-With 头 |
| alpine-morph | Alpine.js 现在有一个轻量级的 morph 插件，这个扩展允许你将其用作 htmx 中的交换机制，当你通过 htmx 交换整个 Alpine 组件时，这对于保留 Alpine 状态。 |
| class-tools | class-tools 扩展允许你使用 classes 或 data-classes 属性指定将在元素上或元素外交换的 CSS 类。 |
| client-side-templates | 此扩展支持通过客户端模板将 JSON/XML 请求响应转换为 HTML，然后再交换到 DOM。 |
| debug | 此扩展包括通过带 DEBUG: 前缀的函数 console.debug 或 console.log 记录其所在元素的所有 htmx 事件。 |
| disable-element | 当在触发请求的元素上配置时此扩展在 htmx 请求期间禁用元素。请注意，此功能现在通过属性 hx-disabled-elt 成为 htmx 核心的一部分 |
| event-header | 此扩展将 Triggering-Event 头添加到请求中。HTTP 头的值是触发请求的事件的 JSON 序列化格式。 |
| include-vals | 此 include-vals 扩展允许你以编程方式使用 include-vals 属性在请求中包含值。此属性的值是一个或多个名称/值对，它们将被视为 javascript 对象文字中的字段。 |
| json-enc-custom | 此扩展的工作原理与 json-enc 类似，但允许非常复杂的结构，例如嵌入 JSON 对象、列表或处理索引，只需使用名称属性即可。 |
| json-enc | 此扩展以 JSON 格式而不是 url 格式对参数进行编码。 |
| loading-states | 此扩展允许你在请求正在进行时轻松管理加载状态，包括禁用元素以及添加和删除 CSS 类。 |
| morphdom-swap | 提供基于morphdom变形库 morph 的交换策略。 |
| multi-swap | 此扩展允许你交换 HTML 响应中标记的多个元素。你还可以为每个元素选择应使用的交换方法。 |
| no-cache | 此扩展强制 HTMX 绕过客户端缓存并发出新请求。还添加了一个 hx-no-cache 头以允许绕过服务器端缓存。 |
| path-deps | 受到 intercooler.js 依赖机制的启发，此扩展支持根据路径表达元素间的依赖关系。 |
| path-params | 此扩展使用请求参数来填充路径变量。已使用的参数已被删除，因此它们将不再在查询字符串或正文中发送。 |
| remove-me | 允许你在指定的间隔后删除元素。 |
| replace-params | 此扩展使用请求参数替换现有参数。如果给定值为空字符串，则参数将被删除。此扩展在你只想替换少数参数而不是重置所有参数、分页、搜索等情况下非常有用，。 |
| restored | 使用时检测到后退按钮时触发 hx-boost 事件 |
| safe-nonce | 该safe-nonce扩展可用于提高应用程序/网站的安全性，并通过允许你安全地返回已知的受信任内联脚本来帮助避免 XSS 问题 |
| signalr | 通过 SignalR 提供双向实时通信。 |
| amz-content-sha256 | HTMX 扩展用于与AWS 服务交互时对内容哈希作为数据完整性验证请求的一部分。 |
| hx-drag | 该扩展允许 htmx 发送拖放事件 |