hx-swap-oob

Синтаксис

<div id="alerts" hx-swap-oob="true">
    Alert message
</div>

Рассмотрим следующий HTML-код ответа:

<div>
 ...
</div>
<div id="alerts" hx-swap-oob="true">
    Saved!
</div>

Первый <div> заменяется в основном целевом элементе.

Второй заменяет существующий элемент #alerts за пределами этого целевого элемента.

Значением hx-swap-oob может быть:

• true
• любое допустимое значение hx-swap
• любое допустимое значение hx-swap, за которым следует двоеточие, а затем CSS-селектор

Если значение равно true или outerHTML (эти значения эквивалентны), элемент будет заменён встроенным способом.

Если указано значение стратегии замены, будет использована эта стратегия, а окружающая пара тегов будет удалена для всех стратегий, кроме outerHTML.

Если указан селектор, будут заменены все соответствующие ему элементы. Если селектор не указан, будет заменён элемент с ID, совпадающим с ID нового содержимого.

Использование альтернативных стратегий замены

Стратегии замены, отличные от true или outerHTML, удаляют обёртку. Используйте обёртку, допустимую в контексте целевого элемента.

При попытке вставить <tr> в таблицу, использующую <tbody>:

<tbody hx-swap-oob="beforeend:#table tbody">
	<tr>
		...
	</tr>
</tbody>

Обычная таблица:

<table hx-swap-oob="beforeend:#table2">
	<tr>
		...
	</tr>
</table>

Элемент <li> можно обернуть в <ul>, <ol>, <div> или <span>, например:

<ul hx-swap-oob="beforeend:#list1">
	<li>...</li>
</ul>

Элемент <p> можно обернуть в <div> или <span>:

<span hx-swap-oob="beforeend:#text">
	<p>...</p>
</strong>

Проблемные таблицы и списки

Используйте <template> для обёртывания элементов, которые не могут находиться в HTML отдельно:

<tr>, <td>, <th>, <thead>, <tbody>, <tfoot>, <colgroup>, <caption>, <col> и <li>.

Вот пример внеполосной замены строки таблицы, обёрнутой таким образом:

<div>
    ...
</div>
<template>
    <tr id="row" hx-swap-oob="true">
        ...
    </tr>
</template>

Обратите внимание, что эти теги шаблона будут удалены из итогового содержимого страницы.

Непростые SVG

Дочерним элементам SVG требуется пространство имён SVG.

Оберните их в <template><svg>, чтобы браузер применил правильное пространство имён.

Вот пример внеполосной замены элементов SVG, обёрнутых таким образом:

<div>
    ...
</div>
<template><svg>
    <circle hx-swap-oob="true" id="circle1" r="35" cx="50" cy="50" fill="red" /> 
</svg></template>
<template><svg hx-swap-oob="beforebegin:#circle1">
    <circle id="circle2" r="45" cx="50" cy="50" fill="blue" /> 
</svg></template>

Элемент circle1 будет заменён встроенным способом, а затем circle2 будет вставлен перед circle1.

Обратите внимание, что эти теги-обёртки template и svg будут удалены из итогового содержимого страницы.

Вложенные внеполосные замены

По умолчанию htmx обрабатывает каждый элемент hx-swap-oob в ответе, включая элементы, вложенные в основное содержимое.

Это может удалить вложенные фрагменты шаблонов, которые должны остаться при основной замене.

Установите htmx.config.allowNestedOobSwaps в значение false, чтобы обрабатывать только OOB-элементы, расположенные рядом с основным содержимым.

Атрибуты вложенных OOB-элементов удаляются, но сами элементы не заменяются.

Поведение при пустом ответе

По умолчанию ответ, содержащий только OOB-элементы, не приводит к пустой основной замене.

Чтобы разрешить пустую основную замену после извлечения OOB-элементов, установите htmx.config.allowEmptySwapAfterOOB в значение true или используйте модификатор swapEmpty для отдельного элемента:

<form hx-post="/submit" hx-swap="outerHTML swapEmpty:true">

<hx-partial> всегда предотвращает пустую основную замену независимо от настройки allowEmptySwapAfterOOB. Частичные ответы предназначены для чёткого разделения ответа, при котором сервер явно управляет тем, что и куда заменяется.

См. также

• <hx-partial> — альтернатива для обновления нескольких целевых элементов с явным управлением выбором целей и стратегией замены