交换

htmx 提供了几种不同的方法来交换返回到 DOM 中的 HTML。默认情况下,内容会替换目标元素的 innerHTML 。你可以使用 hx-swap 属性修改此设置,其值为以下任意值:

名称 描述
innerHTML 默认值,将内容放在目标元素内
outerHTML 用返回的内容替换整个目标元素
afterbegin 将内容添加到目标中第一个子元素之前
beforebegin 将内容添加到目标父元素中的目标之前
beforeend 将内容附加到目标中的最后一个子项之后
afterend 将内容附加到目标父元素中的目标之后
delete 无论响应如何,都会删除目标元素
none 不附加来自响应的内容(带外交换和响应头仍将被处理)

变形交换

除了上述标准交换机制外,htmx 还支持通过扩展进行变形交换。Morphing swaps 尝试将新内容合并到现有 DOM 中,而不是简单地替换它。它们通常在交换操作期间就地改变现有节点,以牺牲更多 CPU 为代价,从而更好地保留焦点、视频状态等内容。

以下扩展可用于变形样式交换:

  • Idiomorph — 由 htmx 开发人员创建的变形算法。
  • Morphdom Swap - 基于morphdom,原始 DOM 变形库。
  • Alpine-morph - 基于alpine morph插件,与 alpine.js 配合良好

视图转换

新的实验性 View Transitions API 为开发人员提供了一种在不同 DOM 状态之间创建动画过渡的方法。它仍处于积极开发阶段,并非在所有浏览器中都可用,但 htmx 提供了一种使用这个新 API 的方法,如果 API 在给定浏览器中不可用,则回退到非转换机制。

你可以使用以下方法试验这个新的 API:

  • 将配置 htmx.config.globalViewTransitions 变量设置为 true 对所有交换使用转换
  • 在属性 hx-swap 中使用 transition:true 选项
  • 如果由于上述任一配置而导致元素交换转换,你可以捕获该 htmx:beforeTransition 事件并调用 preventDefault() 来取消它的转换。

如 Chrome 文档中有关该功能所述,可以使用 CSS 配置视图转换。

你可以在动画示例页面上看到视图转换示例。

交换选项

hx-swap 属性支持许多选项来调整 htmx 的交换行为。例如,默认情况下,htmx 将在找到的标题标签的标题中任何位置交换新内容。您可以通过将 ignoreTitle 修饰符设置为 true 来关闭此行为:

<button hx-post="/like" hx-swap="outerHTML ignoreTitle:true">Like</button>

可用的修饰符hx-swap有:

选项 描述
transition true 或者 false,是否使用视图转换 API 进行此交换
swap 在清除旧内容和插入新内容之间使用的交换延迟(例如100ms)
settle 在插入新内容和固定新内容之间使用的结算延迟(例如100ms)
ignoreTitle 如果设置为true,则新内容中找到的任何标题都将被忽略,并且不会更新文档标题
scroll top 或 bottom,将目标元素滚动到其顶部或底部
show top 或者 bottom,将目标元素滚动到视图的顶部或底部

所有交换修饰符在指定交换样式后出现,并以英文冒号分隔。

有关这些选项的更多详细信息,请参阅 hx-swap 文档。