hx-swap

hx-swap 属性允许你指定如何相对于 AJAX 请求的 target 交换响应。如果你未指定选项，则默认为 htmx.config.defaultSwapStyle (innerHTML)。

¥The hx-swap attribute allows you to specify how the response will be swapped in relative to the target of an AJAX request. If you do not specify the option, the default is htmx.config.defaultSwapStyle (innerHTML).

此属性的可能值为：

¥The possible values of this attribute are:

这些选项基于标准 DOM 命名和 Element.insertAdjacentHTML 规范。

¥These options are based on standard DOM naming and the Element.insertAdjacentHTML specification.

因此在此代码中：

¥So in this code:

  <div hx-get="/example" hx-swap="afterend">Get Some HTML & Append It</div>

div 会向 /example 发出请求，并将返回的内容附加到 div 后面

¥The div will issue a request to /example and append the returned content after the div

修饰符

¥Modifiers

hx-swap 属性支持用于更改交换行为的修饰符。它们概述如下。

¥The hx-swap attributes supports modifiers for changing the behavior of the swap. They are outlined below.

过渡：transition

¥Transition: transition

如果你想在发生交换时使用新的 视图转换 API，则可以使用 transition:true 选项进行交换。你还可以通过将 htmx.config.globalViewTransitions 配置设置设置为 true 来全局启用此功能。

¥If you want to use the new View Transitions API when a swap occurs, you can use the transition:true option for your swap. You can also enable this feature globally by setting the htmx.config.globalViewTransitions config setting to true.

时间：swap & settle

¥Timing: swap & settle

你可以通过包含 swap 修饰符来修改 htmx 在收到响应后等待交换内容的时间：

¥You can modify the amount of time that htmx will wait after receiving a response to swap the content by including a swap modifier:

  <!-- this will wait 1s before doing the swap after it is received -->
  <div hx-get="/example" hx-swap="innerHTML swap:1s">Get Some HTML & Append It</div>

同样，你可以通过包含 settle 修饰符来修改交换和结算逻辑之间的时间：

¥Similarly, you can modify the time between the swap and the settle logic by including a settle modifier:

  <!-- this will wait 1s before doing the swap after it is received -->
  <div hx-get="/example" hx-swap="innerHTML settle:1s">Get Some HTML & Append It</div>

这些属性可用于将 htmx 与 CSS 过渡效果的时间同步。

¥These attributes can be used to synchronize htmx with the timing of CSS transition effects.

标题：ignoreTitle

¥Title: ignoreTitle

默认情况下，如果 htmx 在响应内容中找到 <title> 标签，它将更新页面的标题。你可以通过将 ignoreTitle 选项设置为 true 来关闭此行为。

¥By default, htmx will update the title of the page if it finds a <title> tag in the response content. You can turn off this behavior by setting the ignoreTitle option to true.

滚动：scroll & show

¥Scrolling: scroll & show

你还可以使用 scroll 和 show 修饰符更改目标元素的滚动行为，这两个修饰符均采用值 top 和 bottom：

¥You can also change the scrolling behavior of the target element by using the scroll and show modifiers, both of which take the values top and bottom:

  <!-- this fixed-height div will scroll to the bottom of the div after content is appended -->
  <div style="height:200px; overflow: scroll" 
       hx-get="/example" 
       hx-swap="beforeend scroll:bottom">
     Get Some HTML & Append It & Scroll To Bottom
  </div>

  <!-- this will get some content and add it to #another-div, then ensure that the top of #another-div is visible in the 
       viewport -->
  <div hx-get="/example" 
       hx-swap="innerHTML show:top"
       hx-target="#another-div">
    Get Some Content
  </div>

如果你希望针对不同的元素进行滚动或显示，则可以在 scroll: 或 show: 之后放置一个 CSS 选择器，然后是 :top 或 :bottom：

¥If you wish to target a different element for scrolling or showing, you may place a CSS selector after the scroll: or show:, followed by :top or :bottom:

  <!-- this will get some content and swap it into the current div, then ensure that the top of #another-div is visible in the 
       viewport -->
  <div hx-get="/example" 
       hx-swap="innerHTML show:#another-div:top">
    Get Some Content
  </div>

你还可以使用 window:top 和 window:bottom 滚动到当前窗口的顶部和底部。

¥You may also use window:top and window:bottom to scroll to the top and bottom of the current window.

  <!-- this will get some content and swap it into the current div, then ensure that the viewport is scrolled to the
       very top -->
  <div hx-get="/example" 
       hx-swap="innerHTML show:window:top">
    Get Some Content
  </div>

对于增强链接和表单，默认行为是 show:top。你可以使用 htmx.config.scrollIntoViewOnBoost 全局禁用它，也可以在元素基础上使用 hx-swap="show:none"。

¥For boosted links and forms the default behaviour is show:top. You can disable it globally with htmx.config.scrollIntoViewOnBoost or you can use hx-swap="show:none" on an element basis.

<form action="/example" hx-swap="show:none">
  ...
</form>

焦点滚动

¥Focus scroll

htmx 在具有已定义 id 属性的输入请求之间保留焦点。默认情况下，htmx 会阻止在请求之间自动滚动到焦点输入，当用户已经滚动离开时，这可能是较长请求的不良行为。要启用焦点滚动，你可以使用 focus-scroll:true。

¥htmx preserves focus between requests for inputs that have a defined id attribute. By default htmx prevents auto-scrolling to focused inputs between requests which can be unwanted behavior on longer requests when the user has already scrolled away. To enable focus scroll you can use focus-scroll:true.

  <input id="name" hx-get="/validation" 
       hx-swap="outerHTML focus-scroll:true"/>

或者，如果你希望页面在每次请求后自动滚动到焦点元素，你可以将 htmx 全局配置值 htmx.config.defaultFocusScroll 更改为 true。然后使用 focus-scroll:false 针对特定请求禁用它。

¥Alternatively, if you want the page to automatically scroll to the focused element after each request you can change the htmx global configuration value htmx.config.defaultFocusScroll to true. Then disable it for specific requests using focus-scroll:false.

  <input id="name" hx-get="/validation" 
       hx-swap="outerHTML focus-scroll:false"/>

注释

¥Notes