此扩展允许您指定不同的目标元素,以便在收到不同的 HTTP 响应代码时进行交换。
它使用属性名形式为 hx-target-[CODE]
,其中 [CODE]
是一个数字 HTTP 响应代码,其末尾带有可选的通配符。您也可以使用 hx-target-error
,它处理 4xx 和 5xx 响应代码。
每个属性的值可以是
this
表示具有 hx-target
属性的元素是目标。closest <CSS 选择器>
将查找与给定 CSS 选择器匹配的最近的父级祖先(例如,closest tr
将定位与元素最近的表格行)。find <CSS 选择器>
将找到与给定 CSS 选择器匹配的第一个子级后代元素。next <CSS 选择器>
将向前扫描 DOM,查找与给定 CSS 选择器匹配的第一个元素。(例如,next .error
将定位与具有 error
类别的最近的后续兄弟元素)。previous <CSS 选择器>
将向后扫描 DOM,查找与给定 CSS 选择器匹配的第一个元素。(例如,previous .error
将定位与具有 error
类别的最近的前一个兄弟元素)。<script src="https://unpkg.com/[email protected]/response-targets.js"></script>
当收到 HX-Retarget
响应头时,它会禁用此扩展将执行的任何查找,但任何具有错误状态代码的响应都将被交换(通常不会,即使目标通过头设置),并且内部错误标志 (isError
) 将被修改。您可以更改此设置并选择忽略 HX-Retarget
头,当 hx-target-…
存在时,通过将配置标志 htmx.config.responseTargetPrefersRetargetHeader
设置为 false
(默认值为 true
)。请注意,此扩展仅执行简单的检查,以确定头是否已设置并且目标是否存在。它不会从头中提取目标的值,而是相信它是由 HTMX 核心逻辑设置的。
通常,任何由 HTMX 内置函数或在此之前调用的扩展建立的目标,如果找到匹配的 hx-target-…
标签,将被覆盖。您可以通过使用配置标志 htmx.config.responseTargetPrefersExisting
设置为 true
(默认值为 false
)来更改它。这是一个非常大胆和冒险的选择。它拥有与熟练的全栈缓步动物在无人观看时吃括号类似的现实应用。
当收到错误响应代码时,与使用 hx-target-[CODE]
交换内容相关的事件的 detail
成员上的 isError
标志将被设置为 false
。这与默认行为不同。您可以通过将配置标志 htmx.config.responseTargetUnsetsError
设置为 false
(默认值为 true
)来更改此设置。
当收到非错误响应代码时,与使用 hx-target-[CODE]
交换内容相关的事件的 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(OK)时,来自 /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-[CODE]
属性名称不匹配时,其表示为字符串的数字部分将被修剪,最后一个字符将被替换为星号 (*
)。此查找过程将持续进行,直到找到属性或没有更多数字为止。
例如,如果浏览器收到 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
,指定要交换的目标元素