hx-swap

Атрибут hx-swap позволяет указать, как ответ будет заменён относительно цели таргета запроса AJAX. Если вы не укажете параметр, значение по умолчанию — htmx.config.defaultSwapStyle (innerHTML).

Возможные значения этого атрибута:

• innerHTML — Заменить внутренний HTML элемента-цели
• outerHTML — Заменить весь элемент-цель ответом
• beforebegin — Вставить ответ перед элементом-целью
• afterbegin — Вставить ответ перед первым дочерним элементом элемента-цели
• beforeend — Вставить ответ после последнего дочернего элемента элемента-цели
• afterend — Вставить ответ после элемента-цели
• delete — Удалить элемент-цель независимо от ответа
• none — Не добавлять содержимое из ответа (элементы вне зоны видимости всё ещё будут обработаны).

Эти варианты основаны на стандартной номенклатуре DOM и спецификации Element.insertAdjacentHTML.

Итак, в этом коде:

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

Атрибут div отправит запрос на /example и добавит возвращённое содержимое после div.

Модификаторы

Атрибут hx-swap поддерживает модификаторы для изменения поведения замены. Они описаны ниже.

Переход: transition

Если вы хотите использовать новую API переходов переходов просмотров при замене, вы можете использовать опцию transition:true для вашей замены. Также вы можете включить эту функцию глобально, установив конфигурационный параметр htmx.config.globalViewTransitions в true.

Время: swap и settle

Вы можете изменить время, которое htmx будет ждать после получения ответа, чтобы заменить содержимое, включив модификатор swap:

<!-- 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:

<!-- 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>

Если вы хотите нацелить прокрутку или отображение на другой элемент, вы можете поместить CSS-селектор после scroll: или show:, за которым следует :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"/>

Примечания

• hx-swap наследуется и может быть размещён на родительском элементе
• Значение по умолчанию для этого атрибута — innerHTML
• Из-за ограничений DOM невозможно использовать метод outerHTML на элементе <body>. htmx изменит outerHTML на <body> для использования innerHTML.
• Значение задержки замены по умолчанию — 0мс
• Значение задержки обработки завершения по умолчанию — 20мс