事件

Htmx 提供了一个广泛的事件系统，可用于修改和增强行为。事件如下所示。

事件 - htmx:abort

此事件与其他事件不同：htmx 不会触发它，而是监听它。

如果您向发出请求的元素发送 htmx:abort 事件，它将中止请求：

<button id="request-button" hx-post="/example">发出请求</button>
<button onclick="htmx.trigger('#request-button', 'htmx:abort')">取消请求</button>

事件 - htmx:afterOnLoad

此事件在 AJAX onload 完成后触发。请注意，这并不意味着内容已被交换或稳定，仅表示请求已完成。

详情

事件 - htmx:afterProcessNode

此事件在 htmx 初始化 DOM 节点后触发。扩展程序可以借此在节点上构建额外功能。

详情

事件 - htmx:afterRequest

此事件在 AJAX 请求完成后触发，无论是成功请求（即使返回了如 404 的远程错误码）还是网络错误情况。此事件可与 htmx:beforeRequest 配对，围绕请求周期封装行为。

详情

事件 - htmx:afterSettle

此事件在 DOM 稳定 后触发。

详情

事件 - htmx:afterSwap

此事件在新内容被 交换到 DOM 后触发。

详情

事件 - htmx:beforeCleanupElement

此事件在 htmx 禁用 元素或将其从 DOM 中移除前触发。

详情

事件 - htmx:beforeOnLoad

此事件在任何响应处理发生前触发。如果在事件上调用 preventDefault() 取消它，则不会发生交换。

详情

事件 - htmx:beforeProcessNode

此事件在 htmx 初始化 DOM 节点并处理其所有 hx- 属性前触发。这使扩展程序和其他外部代码能够在处理前修改 DOM 节点的内容。

详情

事件 - htmx:beforeRequest

此事件在发出 AJAX 请求前触发。如果在事件上调用 preventDefault() 取消它，则不会发生请求。

详情

事件 - htmx:beforeSend

此事件在请求发送前立即触发。您无法通过此事件取消请求。

详情

事件 - htmx:beforeSwap

此事件在任何新内容被 交换到 DOM 前触发。detail 上的大多数值可被设置以覆盖后续行为，响应头优先级更高的情况除外。如果在事件上调用 preventDefault() 取消它，则不会发生交换。

您可以通过修改事件详情的 shouldSwap、selectOverride、swapOverride 和 target 属性来修改默认交换行为。有关更多详情，请参阅 配置交换 文档。

详情

事件 - htmx:beforeTransition

此事件在 视图过渡 包装的交换发生前触发。如果在事件上调用 preventDefault() 取消它，则不会发生视图过渡，而是执行正常的交换逻辑。

详情

事件 - htmx:configRequest

此事件在 htmx 收集要包含在请求中的参数后触发。可用于包含或更新 htmx 将发送的参数：

document.body.addEventListener('htmx:configRequest', function(evt) {
    evt.detail.parameters['auth_token'] = getAuthToken(); // 向参数中添加一个新参数
});

注意，如果输入值多次出现，parameters 对象中的值将是数组而非单个值。

详情

事件 - htmx:confirm

此事件在每次触发请求时触发（不仅限于具有 hx-confirm 属性的元素）。它允许您取消（或延迟）发出 AJAX 请求。如果在事件上调用 preventDefault()，则不会发出给定请求。detail 对象包含一个函数 evt.detail.issueRequest(skipConfirmation=false)，可用于在稍后时间点发出实际的 AJAX 请求。结合这两个功能，您可以创建异步确认对话框。

以下是一个基本示例，展示了 htmx:confirm 事件的基本用法，不改变默认行为：

document.body.addEventListener('htmx:confirm', function(evt) {
  // 0. 要仅修改具有 hx-confirm 属性的元素的行为，
  //    检查 evt.detail.target.hasAttribute('hx-confirm')

  // 1. 阻止默认行为（这将阻止请求发出）
  evt.preventDefault();
  
  // 2. 在此执行您自己的逻辑
  console.log(evt.detail)

  // 3. 在准备就绪时手动发出请求
  evt.detail.issueRequest(); // 或 evt.detail.issueRequest(true) 以跳过内置的 window.confirm()
});

以下是一个使用 sweet alert 的示例，适用于任何具有 confirm-with-sweet-alert="{question}" 属性的元素：

document.body.addEventListener('htmx:confirm', function(evt) {
  // 1. 显示 sweet alert 的要求是元素具有 confirm-with-sweet-alert
  //    属性，如果没有，我们可以提前返回并让默认行为发生
  if (!evt.detail.target.hasAttribute('confirm-with-sweet-alert')) return

  // 2. 从属性中获取问题
  const question = evt.detail.target.getAttribute('confirm-with-sweet-alert');

  // 3. 阻止默认行为（这将阻止请求发出）
  evt.preventDefault();

  // 4. 显示 sweet alert
  swal({
    title: "确定吗？",
    text: question || "确定要继续吗？",
    icon: "warning",
    buttons: true,
    dangerMode: true,
  }).then((confirmed) => {
    if (confirmed) {
      // 5. 如果用户确认，我们可以手动发出请求
      evt.detail.issueRequest(true); // true 表示跳过内置的 window.confirm()
    }
  });
});
详情

事件 - htmx:historyCacheError

此事件在尝试将缓存保存到 localStorage 失败时触发

详情

事件 - htmx:historyCacheHit

此事件在恢复历史记录时发生缓存命中时触发

您可以通过 preventDefault() 阻止历史记录恢复，以允许替代的恢复处理。如果需要，您也可以在此事件中覆盖历史记录恢复请求的详细信息

详情

事件 - htmx:historyCacheMiss

此事件在恢复历史记录时发生缓存未命中时触发

您可以通过 preventDefault() 阻止历史记录恢复，以允许替代的恢复处理。在向远程服务器发出请求以恢复历史记录之前，您可以修改 xhr 请求或其他详细信息

详情

事件 - htmx:historyCacheMissLoadError

此事件在发生缓存未命中且已从服务器检索到要恢复的内容响应，但响应是错误（例如 404）时触发

详情

事件 - htmx:historyCacheMissLoad

此事件在发生缓存未命中且已成功从服务器检索到要恢复的内容响应时触发

您可以在交换以恢复历史记录之前修改详细信息

详情

事件 - htmx:historyRestore

此事件在 htmx 处理历史记录恢复操作时触发

详情

事件 - htmx:beforeHistorySave

此事件在内容保存到历史缓存前触发。

您可以修改 historyElt 的内容以移除第三方 JavaScript 更改，从而可以将内容的干净副本备份到历史缓存

详情

事件 - htmx:load

此事件在 htmx 将新节点加载到 DOM 时触发。请注意，此事件也在 htmx 首次初始化时触发，文档 body 作为目标。

详情

事件 - htmx:noSSESourceError

此事件在元素在其触发器中引用 SSE 事件但未定义父级 SSE 源时触发

详情

事件 - htmx:oobAfterSwap

此事件作为 带外交换 的一部分触发，行为与 交换后事件 相同

详情

事件 - htmx:oobBeforeSwap

此事件作为 带外交换 的一部分触发，行为与 交换前事件 相同

详情

事件 - htmx:oobErrorNoTarget

此事件在 带外交换 在 DOM 中没有对应元素可交换时触发。

详情

事件 - htmx:onLoadError

此事件在 AJAX 调用的 load 处理期间发生错误时触发

详情

事件 - htmx:prompt

此事件在使用 hx-prompt 属性向用户显示提示后触发。如果取消此事件，则不会发生 AJAX 请求。

详情

事件 - htmx:beforeHistoryUpdate

此事件在执行历史更新前触发。可用于修改用于更新历史的 path 或 type。

详情

事件 - htmx:pushedIntoHistory

此事件在 URL 被推入历史记录后触发。

详情

事件 - htmx:replacedInHistory

此事件在 URL 在历史记录中被替换后触发。

详情

事件 - htmx:responseError

此事件在发生 HTTP 错误响应时触发

详情

事件 - htmx:sendAbort

此事件在请求中止时触发

详情

事件 - htmx:sendError

此事件在网络错误阻止 HTTP 请求发生时触发

详情

事件 - htmx:sseError

此事件在 SSE 源发生错误时触发

详情

事件 - htmx:swapError

此事件在交换阶段发生错误时触发

详情

事件 - htmx:targetError

此事件在 hx-target 属性使用了错误的选择器时触发（例如没有前缀 # 的元素 ID）

详情

事件 - htmx:timeout

此事件在请求超时时触发。它封装了 XMLHttpRequest 的典型 timeout 事件。

可以使用 htmx.config.timeout 或按元素使用 hx-request 设置超时时间

详情

事件 - htmx:trigger

此事件在 AJAX 请求将要发生时触发，即使未指定 AJAX 请求。它主要用于允许 hx-trigger 执行客户端脚本；AJAX 请求有更细粒度的事件可用，如 htmx:beforeRequest 或 htmx:afterRequest。

详情

事件 - htmx:validateUrl

此事件在发出请求前触发，允许您验证 htmx 将要请求的 URL。如果在事件上调用 preventDefault()，则不会发出请求。

document.body.addEventListener('htmx:validateUrl', function (evt) {
  // 仅允许对当前服务器以及 myserver.com 的请求
  if (!evt.detail.sameHost && evt.detail.url.hostname !== "myserver.com") {
    evt.preventDefault();
  }
});
详情

事件 - htmx:validation:validate

此事件在验证元素前触发。可与 elt.setCustomValidity() 方法一起使用，以实现自定义验证规则。

<form hx-post="/test">
  <input _="在 htmx:validation:validate 事件上
               如果 my.value 不等于 'foo'
                  调用 me.setCustomValidity('请输入值 foo')
               否则
                  调用 me.setCustomValidity('')"
         name="example">
</form>
详情

事件 - htmx:validation:failed

此事件在元素验证失败时触发。

详情

事件 - htmx:validation:halted

此事件在因验证错误而停止请求时触发。

详情

事件 - htmx:xhr:abort

此事件在 ajax 请求中止时触发

详情

事件 - htmx:xhr:loadstart

此事件在 ajax 请求开始时触发

详情

事件 - htmx:xhr:loadend

此事件在 ajax 请求完成时触发

详情

事件 - htmx:xhr:progress

此事件在支持进度的 ajax 请求进行期间定期触发

详情