事件

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

事件 - htmx:abort

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

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

<button id="request-button" hx-post="/example">Issue Request</button>
<button onclick="htmx.trigger('#request-button', 'htmx:abort')">Cancel Request</button>

事件 - htmx:afterOnLoad

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

详情

事件 - htmx:afterProcessNode

此事件在 htmx 初始化 DOM 节点后触发。它可用于扩展来为节点构建附加功能。

详情

事件 - htmx:afterRequest

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

详情

事件 - htmx:afterSettle

此事件在 DOM 已 settled 后触发。

详情

事件 - 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

此事件在 View Transition 包装的交换发生之前触发。如果您在事件上调用 preventDefault() 以取消它，则 View Transition 不会发生，而是会发生正常的交换逻辑。

详情

事件 - htmx:configRequest

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

document.body.addEventListener('htmx:configRequest', function(evt) {
    evt.detail.parameters['auth_token'] = getAuthToken(); // add a new parameter into the mix
});

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

详情

事件 - htmx:confirm

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

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

document.body.addEventListener('htmx:confirm', function(evt) {
  // 0. To modify the behavior only for elements with the hx-confirm attribute,
  //    check if evt.detail.target.hasAttribute('hx-confirm')

  // 1. Prevent the default behavior (this will prevent the request from being issued)
  evt.preventDefault();
  
  // 2. Do your own logic here
  console.log(evt.detail)

  // 3. Manually issue the request when you are ready
  evt.detail.issueRequest(); // or evt.detail.issueRequest(true) to skip the built-in window.confirm()
});

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

document.body.addEventListener('htmx:confirm', function(evt) {
  // 1. The requirement to show the sweet alert is that the element has a confirm-with-sweet-alert
  //    attribute on it, if it doesn't we can return early and let the default behavior happen
  if (!evt.detail.target.hasAttribute('confirm-with-sweet-alert')) return

  // 2. Get the question from the attribute
  const question = evt.detail.target.getAttribute('confirm-with-sweet-alert');

  // 3. Prevent the default behavior (this will prevent the request from being issued)
  evt.preventDefault();

  // 4. Show the sweet alert
  swal({
    title: "Are you sure?",
    text: question || "Are you sure you want to continue?",
    icon: "warning",
    buttons: true,
    dangerMode: true,
  }).then((confirmed) => {
    if (confirmed) {
      // 5. If the user confirms, we can manually issue the request
      evt.detail.issueRequest(true); // true to skip the built-in 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

此事件作为 out of band swap 的一部分触发，并与 after swap event 行为相同

详情

事件 - htmx:oobBeforeSwap

此事件作为 out of band swap 的一部分触发，并与 before swap event 行为相同

详情

事件 - htmx:oobErrorNoTarget

此事件在 out of band swap 在 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) {
  // only allow requests to the current server as well as 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('Please enter the value foo')
               else
                  call me.setCustomValidity('')"
         name="example">
</form>
详情

事件 - htmx:validation:failed

此事件在元素验证失败时触发。如果在事件上调用 preventDefault()，则由 htmx.config.reportValidityOfForms 启用的 reportValidity() 不会被调用。

详情

事件 - htmx:validation:halted

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

详情

事件 - htmx:xhr:abort

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

详情

事件 - htmx:xhr:loadstart

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

详情

事件 - htmx:xhr:loadend

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

详情

事件 - htmx:xhr:progress

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

详情