hx-swap-oob

hx-swap-oob 属性允许你指定响应中的某些内容应交换到目标以外的 DOM 中，即 “带外”。这允许你在响应中将更新搭载到其他元素更新上。

¥The hx-swap-oob attribute allows you to specify that some content in a response should be swapped into the DOM somewhere other than the target, that is “Out of Band”. This allows you to piggyback updates to other element updates on a response.

考虑以下响应 HTML：

¥Consider the following response HTML:

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

第一个 div 将以通常的方式交换到目标中。但是，第二个 div 将替换为 id 为 alerts 的元素，并且不会出现在目标中。

¥The first div will be swapped into the target the usual manner. The second div, however, will be swapped in as a replacement for the element with the id alerts, and will not end up in the target.

hx-swap-oob 的值可以是：

¥The value of the hx-swap-oob can be:

如果值为 true 或 outerHTML（它们是等效的），则元素将内联交换。

¥If the value is true or outerHTML (which are equivalent) the element will be swapped inline.

如果给出了交换值，则将使用该交换策略，并且对于除 outerHTML 之外的所有策略，封装标签对将被剥离。

¥If a swap value is given, that swap strategy will be used and the encapsulating tag pair will be stripped for all strategies other than outerHTML.

如果给出了选择器，则将交换与该选择器匹配的所有元素。如果没有，则将交换 ID 与新内容匹配的元素。

¥If a selector is given, all elements matched by that selector will be swapped. If not, the element with an ID matching the new content will be swapped.

使用备用交换策略

¥Using alternate swap strategies

如前所述，当使用除 true 或 outerHTML 以外的交换策略时，封装标签会被剥离，因此你需要使用适合上下文的正确标签来封装返回的数据。

¥As mentioned previously when using swap strategies other than true or outerHTML the encapsulating tags are stripped, as such you need to excapsulate the returned data with the correct tags for the context.

尝试在使用 <tbody> 的表中插入 <tr> 时：

¥When trying to insert a <tr> in a table that uses <tbody>:

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

“plain” 表：

¥A “plain” table:



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

<li> 可以封装在 <ul>、<ol>、<div> 或 <span> 中，例如：

¥A <li> may be encapsulated in <ul>, <ol>, <div> or <span>, for example:

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

<p> 可以封装在 <div> 或 <span> 中：

¥A <p> can be encapsulated in <div> or <span>:

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

麻烦的表格和列表

¥Troublesome Tables and lists

请注意，你可以使用 template 标记来封装根据 HTML 规范不能在 DOM 中独立存在的元素类型（<tr>、<td>、<th>、<thead>、<tbody>、<tfoot>、<colgroup>、<caption>、<col> 和 <li>）。

¥Note that you can use a template tag to encapsulate types of elements that, by the HTML spec, can’t stand on their own in the DOM (<tr>, <td>, <th>, <thead>, <tbody>, <tfoot>, <colgroup>, <caption>, <col> & <li>).

以下是表格行的带外交换以这种方式封装的示例：

¥Here is an example with an out-of-band swap of a table row being encapsulated in this way:

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

请注意，这些模板标签将从页面的最终内容中删除。

¥Note that these template tags will be removed from the final content of the page.

流畅的 SVG

¥Slippery SVGs

一些元素类型（如 SVG）对其子元素使用特定的 XML 命名空间。这会阻止内部元素在交换时正常工作，除非它们封装在 svg 标签内。要修改现有 SVG 的内部内容，你可以同时使用 template 和 svg 标签来封装元素，从而使它们能够应用正确的命名空间。

¥Some element types, like SVG, use a specific XML namespace for their child elements. This prevents internal elements from working correctly when swapped in, unless they are encapsulated within a svg tag. To modify the internal contents of an existing SVG, you can use both template and svg tags to encapsulate the elements, allowing them to get the correct namespace applied.

以下是 svg 元素的带外交换以这种方式封装的示例：

¥Here is an example with an out-of-band swap of svg elements being encapsulated in this way:

<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，然后在 circle1 之前插入 circle2。

¥This will replace circle1 inline and then insert circle2 before circle1.

请注意，这些 template 和 svg 封装标签将从页面的最终内容中删除。

¥Note that these template and svg wrapping tags will be removed from the final content of the page.

嵌套 OOB 交换

¥Nested OOB Swaps

默认情况下，响应中任何位置具有 hx-swap-oob= 属性的任何元素都会被处理以进行 oob 交换行为，包括元素嵌套在主响应元素中的情况。当使用 模板片段 时，这可能会有问题，因为片段可能会被重新用作 oob-swap 目标，也可能被重新用作更大片段的一部分。当较大的片段是主要响应时，内部片段仍将作为 oob 交换进行处理，将其从 dom 中移除。

¥By default, any element with hx-swap-oob= attribute anywhere in the response is processed for oob swap behavior, including when an element is nested within the main response element. This can be problematic when using template fragments where a fragment may be reused as an oob-swap target and also as part of a bigger fragment. When the bigger fragment is the main response the inner fragment will still be processed as an oob swap, removing it from the dom.

可以通过将配置 htmx.config.allowNestedOobSwaps 设置为 false 来更改此行为。如果此配置选项为 false，则仅当元素与主响应元素相邻时才处理 OOB 交换，其他地方的 OOB 交换将被忽略，并且与 oob-swap 相关的属性将被剥离。

¥This behavior can be changed by setting the config htmx.config.allowNestedOobSwaps to false. If this config option is false, OOB swaps are only processed when the element is adjacent to the main response element, OOB swaps elsewhere will be ignored and oob-swap-related attributes stripped.

注释

¥Notes