Events

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

此事件在任何响应处理发生之前触发。如果事件被取消，则不会发生交换。

#详情

#事件 - htmx:beforeProcessNode

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

#详情

#事件 - htmx:beforeRequest

此事件在发出 AJAX 请求之前触发。如果事件被取消，则不会发生请求。

#详情

#事件 - htmx:beforeSend

此事件在请求发送之前触发。你不能使用此事件取消请求。

#详情

#事件 - htmx:beforeSwap

此事件在新内容 交换到 DOM 中 之前触发。如果事件被取消，则不会发生交换。

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

#详情

#事件 - htmx:beforeTransition

此事件在发生 视图转换 包装的交换之前触发。如果事件被取消，将不会发生视图转换，而是执行正常的交换逻辑。

#详情

#事件 - htmx:configRequest

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

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

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

#详情

#事件 - htmx:confirm

此事件在触发器触发后立即触发。它允许你取消（或延迟）发出 AJAX 请求。如果你在事件上调用 preventDefault()，则不会发出请求。detail 对象包含一个函数 evt.detail.issueRequest()，可以用于在稍后发出实际的 AJAX 请求。结合这两个功能，可以创建一个异步确认对话框。

以下是使用 sweet alert 的示例，适用于任何带有 confirm-with-sweet-alert='true' 属性的元素：

document.body.addEventListener('htmx:confirm', function(evt) {
  if (evt.target.matches("[confirm-with-sweet-alert='true']")) {
    evt.preventDefault();
    swal({
      title: "你确定吗？",
      text: "你真的确定吗？",
      icon: "warning",
      buttons: true,
      dangerMode: true,
    }).then((confirmed) => {
      if (confirmed) {
        evt.detail.issueRequest();
      }
    });
  }
});
#详情

{target: target, elt: elt, path: path, verb: verb, triggeringEvent: event, etc: etc, issueRequest: issueRequest}

发出请求（应与 evt.preventDefault() 配对使用！）

#事件 - htmx:historyCacheError

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

#详情

#事件 - htmx:historyCacheMiss

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

#详情

#事件 - htmx:historyCacheMissError

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

#详情

#事件 - htmx:historyCacheMissLoad

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

#详情

#事件 - htmx:historyRestore

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

#详情

#事件 - htmx:beforeHistorySave

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

#详情
#详情

#事件 - htmx:load

此事件在 htmx 将新节点加载到 DOM 中时触发。

#详情

#事件 - 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: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 _="on htmx:validation:validate
               if my.value != 'foo'
                  call me.setCustomValidity('请输入值 foo')
               else
                  call 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 请求进行时周期性触发

#详情