在不丢失状态的情况下移动 DOM 节点
了解如何使用 Element.moveBefore() 移动 DOM 节点并保留 iframe、焦点、动画和对话框状态,同时掌握其语法、限制与回退方案。
Element.moveBefore() 可以移动已在文档中的节点,且不会像 appendChild() 和 insertBefore() 那样执行”先移除、再插入”的步骤。因此,<iframe> 会保留已加载的页面,获得焦点的输入框会保持焦点,正在运行的 CSS 动画也会继续运行。
大多数需要对活动元素重新指定父节点的开发者都遇到过这样的问题:把一张卡片拖到另一列时,其中嵌入的播放器变成空白并重新加载;或者正在输入的文本框在一个单词还没打完时就失去了焦点。
Chrome 在 Chrome 133 中发布了 moveBefore(),该特性在 Chrome 133 发布说明中以 “DOM state-preserving move”(保留 DOM 状态的移动)的名称出现。本文将介绍其语法、一个演示示例、被保留状态的完整列表、错误情形、自定义元素钩子以及安全的降级方案。如果需要先复习基础知识,请参阅在 JavaScript 中操作 DOM 和 DOM 元素的生命周期。
核心要点
parent.moveBefore(node, ref)的参数与insertBefore()相同,但它在移动节点时不会将其移除再重新插入,因此 iframe、焦点、动画、popover 和模态对话框都能保留各自的状态。- 被移动的节点必须是 Element 或 CharacterData 节点。在不同文档之间移动、在已连接树与未连接树之间移动,或移动到节点自身的后代中,都会抛出
HierarchyRequestError。 MutationObserver仍会将一次moveBefore()移动视为一次移除加一次添加。- 定义了
connectedMoveCallback()的自定义元素会调用该回调,而不是disconnectedCallback()和connectedCallback()。 - Safari 不支持
moveBefore(),因此需要检查'moveBefore' in Element.prototype,并降级使用insertBefore()。
为什么 appendChild 和 insertBefore 会重置状态?
每次使用 appendChild() 或 insertBefore() 进行的移动,实际上都是两个操作:浏览器先从文档中移除节点,然后再将其插入。Chrome 团队在发布文章中指出,自早期标准以来,DOM 一直没有其他方式来移动节点。移除节点会销毁那些只在节点处于连接状态时才存在的状态:iframe 会卸载并重新加载其文档,获得焦点的元素会失去焦点,CSS 动画会从头开始,已打开的 popover 和模态对话框会被关闭。
在可重新排序的仪表盘的会话回放中,这类 bug 通常表现为:用户拖动一张卡片后继续输入,但由于输入框已失去焦点,按键输入没有生效;嵌入的 iframe 也会在会话过程中明显地重新加载。
moveBefore() 语法
moveBefore() 接受与 insertBefore() 相同的两个参数:要移动的节点和参考节点。将参考节点传为 null 时,节点会被移动到父节点子元素列表的末尾。
parent.moveBefore(movedNode, referenceNode);
parent.moveBefore(movedNode, null); // append
根据 MDN 的 moveBefore() 参考文档,被移动的节点必须是 Element 或 CharacterData 节点。文本节点是允许的,但诸如文档类型节点则不允许。该方法同样存在于 Document 和 DocumentFragment 上,因此即使 fragment 从未连接到文档,也可以在其内部移动节点。该方法定义于 DOM Living Standard 中。
演示:使用与不使用 moveBefore 移动 iframe
要直观地看出差异,最快的方法是使用一个带有内部状态的 iframe。此演示使用 srcdoc,因此不会发出任何网络请求。
<div id="left" class="box">
<iframe id="frame" srcdoc="<button onclick='this.textContent=++n'>0</button><script>let n=0</script>"></iframe>
</div>
<div id="right" class="box"></div>
<button id="viaInsert">Move with insertBefore()</button>
<button id="viaMove">Move with moveBefore()</button>
<script>
const frame = document.getElementById('frame');
const left = document.getElementById('left');
const right = document.getElementById('right');
const target = () => (frame.parentElement === left ? right : left);
document.getElementById('viaInsert').onclick = () =>
target().insertBefore(frame, null); // iframe reloads, counter back to 0
document.getElementById('viaMove').onclick = () =>
target().moveBefore(frame, null); // counter value survives
</script>
先点击 frame 内的计数器几次,然后分别尝试两个按钮。insertBefore() 会重新加载 frame,计数器归零;moveBefore() 则会保留计数。第二个按钮只在支持该方法的浏览器中有效(参见下文的特性检测部分)。
焦点的行为与此相同:
const input = document.querySelector('#note');
input.focus();
sidebar.moveBefore(input, null);
console.log(document.activeElement === input); // true
// With sidebar.insertBefore(input, null), focus is lost
moveBefore() 会保留哪些状态?
moveBefore() 保留的是 MDN 中列出的一组特定状态,而并非所有可能的状态:
- 动画与过渡(transition)状态
<iframe>加载状态:focus和:active- 全屏元素状态
- Popover 打开状态
- 模态
<dialog>状态
原生 <video> 和 <audio> 元素即使通过 appendChild() 或 insertBefore() 移动,也会保留其播放状态。因此对于媒体而言,moveBefore() 的作用体现在播放器嵌入于 <iframe> 中的场景(例如第三方视频嵌入),而不是原生媒体元素。
moveBefore() 的错误与约束
moveBefore() 比 insertBefore() 更严格。在某些情况下,insertBefore() 会静默地执行”移除再插入”,而 moveBefore() 则会直接抛出错误。
| 错误 | 触发条件 | 处理方式 |
|---|---|---|
HierarchyRequestError | 在已连接树与未连接树之间移动 | 使用 insertBefore() |
HierarchyRequestError | 在不同文档之间移动 | 使用 insertBefore()(或先调用 adoptNode()) |
HierarchyRequestError | 将节点移动到其自身的后代中 | 修正目标位置:这是逻辑 bug |
HierarchyRequestError | movedNode 不是 Element 或 CharacterData | 使用 insertBefore() |
NotFoundError | referenceNode 不是父节点的子节点 | 传入真实的子节点或 null |
TypeError | 缺少第二个参数 | 显式传入 null 以追加到末尾 |
TypeError 这一行最容易让人踩坑,因为人们会沿用 insertBefore() 的习惯:只传一个参数调用 moveBefore(node) 是无法实现追加的。
MutationObserver 与 connectedMoveCallback
MutationObserver 仍会把通过 moveBefore() 移动的节点记录为一个被移除的节点和一个被添加的节点,因此现有的观察器仍能收到移动操作的记录。DOM 标准的 move 步骤会为旧父节点排入一条移除记录,并为新父节点排入一条添加记录。如果代码将移除视为”已销毁”,并且需要区分移动与删除,就需要借助其他信号。关于观察器的配置,请参阅 三种 DOM 观察器 API。
自定义元素拥有专门的移动钩子 connectedMoveCallback()。正如 MDN 的自定义元素指南所述,当定义了 connectedMoveCallback() 时,每次元素通过 Element.moveBefore() 被移动到 DOM 中的其他位置,都会调用它,而不是 调用 connectedCallback() 和 disconnectedCallback()。
class DashCard extends HTMLElement {
connectedCallback() { /* initial setup: subscriptions, timers */ }
disconnectedCallback() { /* teardown */ }
connectedMoveCallback() { /* runs instead of the two above on moveBefore() */ }
}
customElements.define('dash-card', DashCard);
如果类中没有定义 connectedMoveCallback(),moveBefore() 移动时仍会先执行 disconnectedCallback(),再执行 connectedCallback()。只要定义了该方法(哪怕是空函数),就会取代这一对回调。HTML 规范中描述了这一行为。
moveBefore 的特性检测与降级方案
调用该方法前,应先检查 'moveBefore' in Element.prototype。当该方法不存在时,或者当它因某个 insertBefore() 能够接受的移动而抛出 HierarchyRequestError 时,都应降级使用 insertBefore()。根据 caniuse 的数据,Chrome 和 Edge 133+ 以及 Firefox 144+ 支持该方法,Safari 不支持。web-features 将其列为 Limited availability(有限可用),而非 Baseline。
function moveNode(parent, node, ref = null) {
if ('moveBefore' in Element.prototype) {
try {
parent.moveBefore(node, ref);
return;
} catch (err) {
if (err.name !== 'HierarchyRequestError') throw err; // NotFoundError etc. are real bugs
}
}
const active = document.activeElement;
parent.insertBefore(node, ref); // state-resetting path
if (active && node.contains(active)) active.focus();
}
insertBefore() 降级路径仍会重新加载 iframe、重启动画并关闭对话框,与 insertBefore() 一贯的行为完全一致。恢复焦点只能让焦点回到元素上,无法保证光标位置不变。此检测仅针对 Element 类型的父节点,并不能说明 Document 或 DocumentFragment 是否支持该方法。
结论
moveBefore() 首次为 DOM 带来了真正意义上的移动操作:只需一次调用,就能让 iframe 保持加载、焦点保持不变、动画继续运行——前提是遵守 MDN 列出的约束。请找出拖放或 DOM morphing 代码中所有用于移动活动节点的 appendChild() 或 insertBefore() 调用,将它们改为通过 moveNode() 这类辅助函数执行,并为那些在重新定位时不应重复执行初始化逻辑的自定义元素添加 connectedMoveCallback()。
常见问题
moveBefore() 能否将元素移入或移出 shadow root?
可以。ShadowRoot 继承自 DocumentFragment,因此它拥有自己的 moveBefore() 方法。移动必须在同一个 shadow-including root 内进行,而对于连接到同一文档的任意节点,已连接的 shadow root 都满足这一要求。将 light DOM 内容移入已连接的 shadow tree 时,焦点、iframe 加载状态以及 MDN 列出的其他状态都会被保留。
为什么插入新创建的元素时 moveBefore() 会抛出错误?
通过 document.createElement() 创建的元素尚未连接到文档。将未连接的节点移入已连接的父节点会抛出 HierarchyRequestError。首次插入时请使用 appendChild() 或 insertBefore()。从未连接过的节点没有需要保留的 iframe、焦点或动画状态,因此不会有任何损失。之后的移动操作再使用 moveBefore()。
能否为 Safari 提供 moveBefore() 的 polyfill?
不能。polyfill 可以添加一个调用 insertBefore() 的 moveBefore() 方法,但这只是复制了方法名。在移动过程中保持 iframe 文档、焦点、动画和已打开的 popover 存活,是由浏览器引擎完成的,JavaScript 无法做到。在不支持原生方法的浏览器中,shim 的行为与 insertBefore() 完全相同,同样会重置这些状态。
是否已有库在使用 moveBefore()?
是的。htmx 在 2024 年 10 月发布的 2.0.3 版本中添加了对 moveBefore() 的支持。当浏览器提供 moveBefore() 时,htmx 会在内容替换期间使用它来移动标记了 hx-preserve 的元素,从而让这些元素保留其状态。在不支持该方法的浏览器中,htmx 会回退到其常规行为,即以传统的"移除再插入"方式移动元素。