htmx 响应目标扩展

此扩展允许你指定在收到不同的 HTTP 响应代码时交换不同目标元素。

它使用 hx-target-[CODE] 形式的属性名称，其中[CODE]是 HTTP 响应代码，末尾带有可选的通配符。你还可以使用 hx-target-error，它可以处理 4xx 和 5xx 响应代码。

每个属性的值可以是：

  • 目标元素的 CSS 查询选择器。
  • 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/[email protected]/response-targets.js"></script>

配置（可选）

  • 当收到HX-Retarget响应报头时，它会禁用此扩展执行的任何查找，但任何具有错误状态代码的响应都将被交换（通常不会交换，即使通过报头设置目标），并且内部错误标志（isError）将被修改。你可以更改此设置，并选择在 hx-target 时忽略 HX-Retarget 报头-...通过将配置标志 htmx.config.responseTargetPrefersRetargetHeader 设置为 false（默认值为 true）来实现。请注意，此扩展仅执行简单的检查是否设置了 header 以及 target 是否存在。它没有从 header 中提取 target 的值，但相信它是由 HTMX 核心逻辑设置的。

  • 通常，如果匹配的 hx-target，则之前调用的 HTMX 内置函数或扩展已经建立的任何目标都将被覆盖-...标签。你可以使用配置标志 htmx.config.responseTargetPrefersExisting 将其更改为 true（默认值为 false）。这是且有风险的选择。

  • 收到错误响应代码时，与使用 hx-target-[CODE] 交换内容关联的事件的详细信息成员上的 isError 标志将设置为 false。这与默认行为不同。你可以通过将配置标志 htmx.config.responseTargetUnsetsError 设置为 false（默认值为 true）来更改此设置。

  • 当收到非错误响应代码时，与使用 hx-target-[CODE] 交换内容关联的事件的详细信息成员上的 isError 标志将设置为 false。这与默认行为没有什么不同。你可以通过将配置标志 htmx.config.responseTargetSetsError 设置为 true（默认值为 false）来更改此设置。此设置不会影响响应代码 200，因为它不由此扩展处理。

用法

下面是一个针对正常（200）响应的示例div，另一个div 针对 404（未找到）响应，还有一个针对所有 5xx 响应代码：

<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 的响应会将 div 的内容替换成 id 为 response-div 的内容。
  • 当响应代码以数字 5（服务器错误）开头时，来自 /register URL 的响应会将 ID 对应的 div 的内容替换为严重错误。
  • 当响应代码为 404 （Not Found） 时，来自 /register URL 的响应会将 id 对应的 div 的内容替换成 not-found。

有时你可能不想分别处理 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 的响应将用 any-errors 替换 id 对应的 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, 指定要交换的目标元素