参考

内容

¥Contents

核心属性参考

¥Core Attribute Reference

使用 htmx 时最常见的属性。

¥The most common attributes when using 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 格式）

其他属性参考

¥Additional Attribute Reference

htmx 中可用的所有其他属性。

¥All other attributes available in 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`	添加到将随请求提交的标头
`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`）

CSS 类参考

¥CSS Class Reference

类	描述
`htmx-added`	在交换新内容之前应用于新内容，在内容稳定后删除。
`htmx-indicator`	当存在 `htmx-request` 类时，动态生成的类将切换为可见（不透明度：1）
`htmx-request`	在请求正在进行时应用于元素或用 `hx-indicator` 指定的元素
`htmx-settling`	在内容交换后应用于目标，在内容稳定后删除。可以通过 `hx-swap` 修改持续时间。
`htmx-swapping`	在交换任何内容之前应用于目标，在交换后删除。可以通过 `hx-swap` 修改持续时间。

HTTP 标头参考

¥HTTP Header Reference

请求标头参考

¥Request Headers Reference

标题	描述
`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`

响应标头参考

¥Response Headers Reference

标题	描述
`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`	允许你在交换步骤后触发客户端事件

事件参考

¥Event Reference

事件	描述
`htmx:abort`	将此事件发送到元素以中止请求
`htmx:afterOnLoad`	在 AJAX 请求完成处理成功响应后触发
`htmx:afterProcessNode`	在 htmx 初始化节点后触发
`htmx:afterRequest`	在 AJAX 请求完成后触发
`htmx:afterSettle`	在 DOM 稳定后触发
`htmx:afterSwap`	在交换新内容后触发
`htmx:beforeCleanupElement`	在 htmx disables 元素或将其从 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 请求期间定期触发

JavaScript API 参考

¥JavaScript API Reference

方法	描述
`htmx.addClass()`	向给定元素添加类
`htmx.ajax()`	发出 htmx 样式的 ajax 请求
`htmx.closest()`	查找与选择器匹配的给定元素的最接近父级
`htmx.config`	保存当前 htmx 配置对象的属性
`htmx.createEventSource`	保存为 htmx 创建 SSE EventSource 对象的函数的属性
`htmx.createWebSocket`	保存为 htmx 创建 WebSocket 对象的函数的属性
`htmx.defineExtension()`	定义 htmx extension
`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 extension
`htmx.swap()`	执行 HTML 内容的交换（和解决）
`htmx.takeClass()`	从其他元素中为给定元素获取一个类
`htmx.toggleClass()`	从给定元素切换类
`htmx.trigger()`	在元素上触发事件
`htmx.values()`	返回与给定元素关联的输入值

配置参考

¥Configuration Reference

Htmx 有一些配置选项，可以通过编程或声明方式访问。它们列在下面：

¥Htmx has some configuration options that can be accessed either programmatically or declaratively. They are listed below:

配置变量	信息
`htmx.config.historyEnabled`	默认为 `true`，真的只对测试有用
`htmx.config.historyCacheSize`	默认为 10
`htmx.config.refreshOnHistoryMiss`	默认为 `false`，如果设置为 `true`，htmx 将在历史记录未命中时发出整页刷新，而不是使用 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`	默认为 `''`，意味着不会向内联脚本添加任何 nonce
`htmx.config.inlineStyleNonce`	默认为 `''`，意味着不会向内联样式添加任何 nonce
`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-inherit 属性明确指定继承。
`htmx.config.withCredentials`	默认为 `false`，允许使用凭据（例如 cookie、授权标头或 TLS 客户端证书）进行跨站点访问控制请求
`htmx.config.timeout`	默认为 0，请求在自动终止前可能需要的毫秒数
`htmx.config.scrollBehavior`	默认为 ‘instant’，将 show 修饰符与 `hx-swap` 一起使用时的滚动行为。允许的值为 `instant`（滚动应在一次跳转中立即发生）、`smooth`（滚动应流畅地进行动画处理）和 `auto`（滚动行为由 scroll-behavior 的计算值决定）。
`htmx.config.defaultFocusScroll`	如果焦点元素应该滚动到视图中，则默认为 false，可以使用 focus-scroll swap 修饰符进行覆盖。
`htmx.config.getCacheBusterParam`	默认为 false，如果设置为 true，htmx 将以 `org.htmx.cache-buster=targetElementId` 格式将目标元素附加到 `GET` 请求
`htmx.config.globalViewTransitions`	如果设置为 `true`，htmx 将在交换新内容时使用查看转换 API。
`htmx.config.methodsThatUseUrlParams`	默认为 `["get", "delete"]`，htmx 将通过在 URL 中编码其参数（而不是请求正文）来格式化使用这些方法的请求
`htmx.config.selfRequestsOnly`	默认为 `true`，是否仅允许对与当前文档相同的域进行 AJAX 请求
`htmx.config.ignoreTitle`	默认为 `false`，如果设置为 `true`，当在新内容中找到 `title` 标记时，htmx 将不会更新文档的标题
`htmx.config.scrollIntoViewOnBoost`	默认为 `true`，增强元素的目标是否滚动到视口中。如果在提升元素上省略 `hx-target`，则目标默认为 `body`，导致页面滚动到顶部。
`htmx.config.triggerSpecsCache`	默认为 `null`，将评估的触发器规范存储到其中的缓存，以更多的内存使用为代价提高解析性能。你可以定义一个简单的对象来使用永不清除的缓存，或者使用代理对象实现你自己的系统
`htmx.config.responseHandling`	响应状态代码的默认响应处理行为可以在此处配置为交换或错误
`htmx.config.allowNestedOobSwaps`	默认为 `true`，是否处理嵌套在主响应元素中的元素的 OOB 交换。参见嵌套 OOB 交换。

你可以直接在 javascript 中设置它们，也可以使用 meta 标签：

¥You can set them directly in javascript, or you can use a meta tag:

<meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>