此擴展允許您指定當接收到不同的 HTTP 回應代碼時要交換的不同目標元素。
它使用 hx-target-[代碼]
形式的屬性名稱,其中 [代碼]
是一個數字 HTTP 回應代碼,結尾可選用萬用字元。您也可以使用 hx-target-error
,它會處理 4xx 和 5xx 回應代碼。
每個屬性的值可以是
this
表示 hx-target
屬性所在的元素本身為目標。closest <CSS selector>
將尋找符合給定 CSS 選擇器的最近父輩祖先 (例如,closest tr
將以元素最近的表格列為目標)。find <CSS selector>
將尋找符合給定 CSS 選擇器的第一個子代後代元素。next <CSS selector>
將在 DOM 中向前掃描符合給定 CSS 選擇器的第一個元素。(例如,next .error
將以具有 error
類別的最近後續兄弟元素為目標)previous <CSS selector>
將在 DOM 中向後掃描符合給定 CSS 選擇器的第一個元素。(例如,previous .error
將以具有 error
類別的最近前一個兄弟元素為目標)<script src="https://unpkg.com/htmx-ext-response-targets@2.0.0/response-targets.js"></script>
當收到 HX-Retarget
回應標頭時,它會停用此擴展所執行的任何查詢,但是任何具有錯誤狀態碼的回應都會被交換 (通常它們不會,即使通過標頭設定目標),且內部錯誤標誌 (isError
) 將被修改。您可以更改此設定,並選擇當存在 hx-target-…
時忽略 HX-Retarget
標頭,方法是將設定標誌 htmx.config.responseTargetPrefersRetargetHeader
設定為 false
(預設為 true
)。請注意,此擴展僅執行簡單的檢查,以判斷標頭是否已設定且目標是否存在。它不會從標頭中提取目標的值,而是信任它是由 HTMX 核心邏輯設定的。
通常,如果找到匹配的 hx-target-…
標籤,任何已由 HTMX 內建函數或之前呼叫的擴展建立的目標都會被覆寫。您可以使用設定標誌 htmx.config.responseTargetPrefersExisting
設定為 true
來更改它 (預設為 false
)。這是一個古怪且有風險的選項。它在現實生活中有一些應用,類似於一位熟練的全端緩步動物在沒人看到時偷偷吃括號。
當收到錯誤回應代碼時,與使用 hx-target-[代碼]
交換內容相關聯的事件的 detail
成員上的 isError
標誌將設定為 false
。這與預設行為不同。您可以通過將設定標誌 htmx.config.responseTargetUnsetsError
設定為 false
來更改此設定 (預設為 true
)。
當收到非錯誤的回應代碼時,與使用 hx-target-[代碼]
交換內容相關聯的事件的 detail
成員上的 isError
標誌將設定為 false
。這與預設行為沒有不同。您可以通過將設定標誌 htmx.config.responseTargetSetsError
設定為 true
來更改此設定 (預設為 false
)。此設定不會影響回應代碼 200,因為此擴展不處理它。
這是一個範例,它針對正常 (200) 回應的 div
,針對 404 (未找到) 回應的另一個 div
,以及針對所有 5xx 回應代碼的又一個 div
<div hx-ext="response-targets">
<div id="response-div"></div>
<button hx-post="/register"
hx-target="#response-div"
hx-target-5*="#serious-errors"
hx-target-404="#not-found">
Register!
</button>
<div id="serious-errors"></div>
<div id="not-found"></div>
</div>
當回應代碼為 200 (確定) 時,來自 /register
URL 的回應將取代 id
為 response-div
的 div
的內容。
當回應代碼以數字 5 (伺服器錯誤) 開頭時,來自 /register
URL 的回應將取代 id
為 serious-errors
的 div
的內容。
當回應代碼為 404 (未找到) 時,來自 /register
URL 的回應將取代 id
為 not-found
的 div
的內容。
有時您可能不想單獨處理 5xx 和 4xx 錯誤,在這種情況下,您可以使用 hx-target-error
<div hx-ext="response-targets">
<div id="response-div"></div>
<button hx-post="/register"
hx-target="#response-div"
hx-target-error="#any-errors">
Register!
</button>
<div id="any-errors"></div>
</div>
2xx 代碼將如上例所示處理。但是,當回應代碼為 5xx 或 4xx 時,來自 /register
的回應將取代 id
為 any-errors
的 div
的內容。
當狀態回應代碼與現有的 hx-target-[代碼]
屬性名稱不匹配時,則將其表示為字串的數值部分進行修剪,並將最後一個字元替換為星號 (*
)。此查詢過程會持續進行,直到找到屬性或沒有更多數字為止。
例如,如果瀏覽器收到 404 錯誤代碼,則會查詢以下屬性名稱 (按給定的順序)
hx-target-404
hx-target-40*
hx-target-4*
hx-target-*
.如果您使用的工具不支援 HTML 屬性中的星號,則可以使用 x
字元,例如,hx-target-4xx
。
hx-target-…
會被繼承,並且可以放置在父元素上。hx-target-…
不能用於處理 HTTP 回應代碼 200。hx-target-…
預設會遵循 HX-Retarget
,並且會優先於任何計算的目標,但是可以通過禁用 htmx.config.responseTargetPrefersRetargetHeader
設定選項來更改此設定。hx-ext
屬性應放置在包含具有 hx-target-…
和 hx-target
屬性的元素的父元素上。hx-target
,指定要交換的目標元素