htmx 头标签支持扩展

head-support 扩展为 htmx 请求的响应中添加了对头标签的支持。

htmx 最初是一个专注于 body 标签内 HTML 部分替换 的库。因此，合并附加信息（例如头标签）并非该库的重点。（这与例如 TurboLinks 相反，后者专注于通过 AJAX 获取的整个网页合并到浏览器中。）

hx-boost 属性使 htmx 更接近于完整的 HTML 文档支持的世界，并且最终添加了对从 head 元素中提取 title 标签的支持，但完整的 head 标签支持从未成为该库的功能。此扩展解决了这一缺陷。

安装

<script src="https://unpkg.com/[email protected]/head-support.js"></script>

使用

<body hx-ext="head-support">
...
</body>

安装后，htmx 收到的所有包含 head 标签的响应（即使它们不是具有根 <html> 元素的完整 HTML 文档）都将被处理。

头标签的处理方式取决于 htmx 请求的类型。

如果 htmx 请求来自一个被增强过的元素，则将使用以下合并算法

当前 head 中存在的与现有文本完全匹配的元素将保留在原位
当前 head 中不存在的元素将添加到 head 标签的末尾
当前 head 中存在，但在新 head 中不存在的元素将从 head 中移除

如果 htmx 请求来自一个未被增强过的元素，则所有内容都将被附加到现有的 head 元素。

如果您希望在任何情况下都覆盖此行为，您可以在新的 <head> 标签上放置 hx-head 属性，并使用以下两种值之一

merge - 遵循上述合并算法
append - 将元素附加到现有的 head

控制合并行为

除此之外，您还可以使用以下属性来控制单个元素的合并行为

如果您在 head 元素上放置 hx-head="re-eval"，它将在每次请求时重新添加到 head 标签（删除并附加），即使它已经存在。例如，这对于在每次 htmx 请求时执行脚本非常有用。
如果您在元素上放置 hx-preserve="true"，它将永远不会从 head 中移除

示例

例如，考虑现有文档中的以下 head 标签

<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site1.css">
<script src="/js/script1.js"></script>
<script src="/js/script2.js"></script>
</head>

如果 htmx 收到包含此新 head 标签的请求

<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script2.js"></script>
<script src="/js/script3.js"></script>
</head>

那么将执行以下操作

<link rel="stylesheet" href="https://the.missing.style"> 将保留
<link rel="stylesheet" href="/css/site1.css"> 将从 head 中移除
<link rel="stylesheet" href="/css/site2.css"> 将添加到 head 中
<script src="/js/script1.js"></script> 将从 head 中移除
<script src="/js/script2.js"></script> 将保留
<script src="/js/script3.js"></script> 将添加到 head 中

最终的 head 元素将如下所示

<head>
<link rel="stylesheet" href="https://the.missing.style">
<script src="/js/script2.js"></script>
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script3.js"></script>
</head>

事件

此扩展触发以下事件

htmx:removingHeadElement - 当即将删除一个 head 元素时触发，即将删除的元素在 event.detail.headElement 中可用。如果在事件上调用 preventDefault()，则该元素将不会被移除。
htmx:addingHeadElement - 当即将添加一个 head 元素时触发，即将添加的元素在 event.detail.headElement 中可用。如果在事件上调用 preventDefault()，则该元素将不会被添加。
htmx:afterHeadMerge - 在 head 标签合并后触发，事件 detail 中提供以下值
added - 添加的 head 元素
kept - 保留的 head 元素
removed - 移除的 head 元素
htmx:beforeHeadMerge - 在 head 合并之前触发