事件

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 完成後觸發。

#詳細資訊

#事件 - 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(); // 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()
});

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

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: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) {
  // 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

當元素驗證失敗時，會觸發此事件。

#詳細資訊

#事件 - htmx:validation:halted

當由於驗證錯誤而暫停請求時，會觸發此事件。

#詳細資訊

#事件 - htmx:xhr:abort

當 ajax 請求中止時，會觸發此事件

#詳細資訊

#事件 - htmx:xhr:loadstart

當 ajax 請求開始時，會觸發此事件

#詳細資訊

#事件 - htmx:xhr:loadend

當 ajax 請求完成時，會觸發此事件

#詳細資訊

#事件 - htmx:xhr:progress

當支援進度的 ajax 請求正在進行中時，會定期觸發此事件

#詳細資訊