Атрибут hx-swap

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

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

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

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

Таким образом, в этом коде:

<div hx-get="/example" hx-swap="afterend">Получить HTML и добавить его</div>

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

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

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

Переход: `transition`

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

Тайминг: `swap` и `settle`

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

<!-- ожидаем 1 секунду перед выполнением замены после получения ответа -->
<div hx-get="/example" hx-swap="innerHTML swap:1s">
  Получить HTML и добавить его
</div>

Вы также можете изменить время между заменой и логикой стабилизации, добавив модификатор settle:

<!-- ожидаем 1 секунду перед выполнением замены после получения ответа -->
<div hx-get="/example" hx-swap="innerHTML settle:1s">
  Получить HTML и добавить его
</div>

Эти атрибуты могут быть использованы для синхронизации htmx с таймингом эффектов CSS-переходов.

Заголовок: `ignoreTitle`

По умолчанию htmx обновит заголовок страницы, если найдет тег <title> в содержимом ответа. Вы можете отключить это поведение, установив опцию ignoreTitle в true.

Прокрутка: `scroll` и `show`

Вы также можете изменить поведение прокрутки целевого элемента, используя модификаторы scroll и show, оба из которых принимают значения top и bottom:

<!-- этот div с фиксированной высотой будет прокручиваться вниз после добавления содержимого -->
<div style="height:200px; overflow: scroll"
    hx-get="/example"
    hx-swap="beforeend scroll:bottom">
  Получить какой-то HTML, добавить его и прокрутить в самый низ
</div>

<!-- получаем некоторое содержимое и добавляем его в #another-div, обеспечивая видимость верхней части #another-div в области просмотра -->
<div hx-get="/example"
    hx-swap="innerHTML show:top"
    hx-target="#another-div">
  Получить какое-то содержимое
</div>

Если вы хотите нацелиться на другой элемент для прокрутки или показа, вы можете указать CSS-селектор после scroll: или show:, за которым следует :top или :bottom:

<!-- получаем некоторое содержимое и добавляем его в текущий div, обеспечивая видимость верхней части #another-div в области просмотра -->
<div hx-get="/example"
    hx-swap="innerHTML show:#another-div:top">
  Получить какое-то содержимое
</div>

Вы также можете использовать window:top и window:bottom, чтобы прокрутить к верхней и нижней части текущего окна:

<!-- получаем некоторое содержимое и добавляем его в текущий div, обеспечивая прокрутку области просмотра к самому верху -->
<div hx-get="/example"
    hx-swap="innerHTML show:window:top">
  Получить какое-то содержимое
</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.
Задержка замены (swap) по умолчанию составляет 0 мс.
Задержка стабилизации (settle) по умолчанию составляет 20 мс.

Атрибут hx-swap

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

Переход: transition

Тайминг: swap и settle

Заголовок: ignoreTitle

Прокрутка: scroll и show