hx-swap

hx-swap 属性を使用すると、AJAXリクエストのターゲットに対して、レスポンスをどのようにスワップするかを指定できます。このオプションを指定しない場合、デフォルトは htmx.config.defaultSwapStyle (innerHTML) になります。

この属性の可能な値は次のとおりです。

これらのオプションは、標準のDOM命名およびElement.insertAdjacentHTML仕様に基づいています。

したがって、次のコードでは

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

div は /example にリクエストを発行し、返されたコンテンツを div の後に追加します

修飾子

hx-swap 属性は、スワップの動作を変更するための修飾子をサポートしています。以下に概要を示します。

遷移: transition

スワップが発生したときに新しいView Transitions APIを使用したい場合は、スワップに transition:true オプションを使用できます。また、htmx.config.globalViewTransitions 設定を true に設定することで、この機能をグローバルに有効にすることもできます。

タイミング: swap & settle

swap 修飾子を含めることで、htmxがレスポンスを受信してからコンテンツをスワップするまで待機する時間を変更できます

  <!-- 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 修飾子を含めることで、スワップとsettleロジック間の時間を変更できます

  <!-- 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遷移効果のタイミングと同期させることができます。

タイトル: ignoreTitle

デフォルトでは、htmxはレスポンスコンテンツに <title> タグがある場合、ページのタイトルを更新します。ignoreTitle オプションをtrueに設定することで、この動作を無効にできます。

スクロール: scroll & show

scroll および show 修飾子を使用して、ターゲット要素のスクロール動作を変更することもできます。どちらも top および 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 を続けます

  <!-- 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 を使用することもできます。

  <!-- 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" を使用できます。

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

フォーカススクロール

htmxは、定義されたid属性を持つ入力の要求間でフォーカスを保持します。デフォルトでは、htmxはリクエスト間でフォーカスされた入力への自動スクロールを防ぎます。これは、ユーザーがすでにスクロールアウトしている長いリクエストでは不要な動作となる可能性があります。フォーカススクロールを有効にするには、focus-scroll:true を使用できます。

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

または、各リクエスト後にページが自動的にフォーカスされた要素にスクロールするようにする場合は、htmxグローバル構成値 htmx.config.defaultFocusScroll をtrueに変更できます。次に、特定の要求に対して focus-scroll:false を使用して無効にします。

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

注意