12k
All articles

Перемещение DOM-узлов без потери состояния

Узнайте, как Element.moveBefore() сохраняет состояние iframe, фокуса, анимаций и диалогов при перемещении DOM-узлов, а также изучите синтаксис и ограничения.

OpenReplay Team
OpenReplay Team
Перемещение DOM-узлов без потери состояния

Element.moveBefore() перемещает узел, который уже находится в документе, без этапа «удалить, затем вставить», который выполняют appendChild() и insertBefore(). Благодаря этому <iframe> сохраняет загруженную страницу, поле ввода с фокусом остаётся в фокусе, а запущенная CSS-анимация продолжает воспроизводиться.

С этой проблемой сталкивалось большинство разработчиков, которым приходилось менять родителя у «живых» элементов: перетаскиваешь карточку в другую колонку, а встроенный в неё плеер очищается и перезагружается, или поле, в котором вы печатали, теряет фокус посреди слова.

Chrome добавил moveBefore() в версии Chrome 133, и эта функция указана в примечаниях к выпуску Chrome 133 как «DOM state-preserving move». В этой статье рассматриваются синтаксис, демонстрационный пример, точный список сохраняемых состояний, ошибки, хуки пользовательских элементов и безопасный запасной вариант. Если сначала нужно освежить основы, прочитайте статьи о работе с DOM в JavaScript и о жизненном цикле 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-анимации начинаются сначала, а открытые всплывающие элементы и модальные диалоги закрываются.

В записях сессий (session replay) дашбордов с перетаскиваемыми элементами эта ошибка обычно выглядит так: пользователь перетаскивает карточку, продолжает печатать, но нажатия клавиш никуда не попадают, потому что поле потеряло фокус. Встроенные iframe заметно перезагружаются прямо посреди сессии.

Синтаксис moveBefore()

moveBefore() принимает те же два аргумента, что и insertBefore(): перемещаемый узел и опорный узел. Если в качестве опорного узла передать null, узел будет перемещён в конец списка дочерних элементов родителя.

parent.moveBefore(movedNode, referenceNode);
parent.moveBefore(movedNode, null); // append

Согласно справочнику MDN по moveBefore(), перемещаемый узел должен быть узлом типа Element или CharacterData. Текстовые узлы допускаются, а, например, узлы типа документа — нет. Метод также есть у Document и DocumentFragment, поэтому узлы можно перемещать и внутри фрагмента, хотя фрагмент никогда не подключается к документу. Метод определён в DOM Living Standard.

Демонстрация: перемещение iframe с moveBefore и без него

Быстрее всего увидеть разницу на примере 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>

Нажмите несколько раз на счётчик внутри фрейма, а затем попробуйте каждую из кнопок. insertBefore() перезагружает фрейм, и счётчик сбрасывается до нуля. 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, а не любое возможное состояние:

  • Состояние анимаций и переходов (transitions)
  • Состояние загрузки <iframe>
  • :focus и :active
  • Состояние полноэкранного элемента
  • Открытое состояние всплывающего элемента (popover)
  • Состояние модального <dialog>

Нативные элементы <video> и <audio> сохраняют состояние воспроизведения даже при перемещении через appendChild() или insertBefore(). Поэтому для медиаконтента moveBefore() важен в случаях, когда плеер встроен в <iframe> (например, видео со стороннего сервиса), а не для нативных медиаэлементов.

Ошибки и ограничения moveBefore()

moveBefore() строже, чем insertBefore(). Он выбрасывает исключения в тех случаях, когда insertBefore() молча выполнил бы удаление и вставку.

ОшибкаКогда возникаетЧто делать
HierarchyRequestErrorПеремещение между подключённым и отключённым деревомИспользовать insertBefore()
HierarchyRequestErrorПеремещение между документамиИспользовать insertBefore() (или сначала adoptNode())
HierarchyRequestErrorПеремещение узла внутрь его собственного потомкаИсправить целевой узел: это логическая ошибка
HierarchyRequestErrormovedNode не является узлом Element или CharacterDataИспользовать insertBefore()
NotFoundErrorreferenceNode не является дочерним узлом родителяПередать реальный дочерний узел или null
TypeErrorОтсутствует второй аргументЯвно передать null для добавления в конец

На строке с TypeError часто спотыкаются из-за привычек, перенесённых с insertBefore(): добавить узел в конец, вызвав moveBefore(node) с одним аргументом, нельзя.

MutationObserver и connectedMoveCallback

MutationObserver по-прежнему регистрирует узел, перемещённый через moveBefore(), как один удалённый и один добавленный узел, поэтому существующие наблюдатели продолжают получать записи о перемещениях. Шаги перемещения в стандарте DOM ставят в очередь запись об удалении для старого родителя и запись о добавлении для нового. Если код считает удаление признаком «уничтожения» узла, ему потребуется другой сигнал, чтобы отличать перемещения от удалений. О настройке наблюдателей читайте в статье о трёх API наблюдателей DOM.

Для пользовательских элементов предусмотрен отдельный хук перемещения — connectedMoveCallback(). Как поясняется в руководстве MDN по пользовательским элементам, если connectedMoveCallback() определён, он вызывается вместо connectedCallback() и disconnectedCallback() каждый раз, когда элемент перемещается в другое место DOM с помощью Element.moveBefore().

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. Найдите в коде drag-and-drop или морфинга DOM все вызовы appendChild() и insertBefore(), которые перемещают «живые» узлы, пропустите их через вспомогательную функцию вроде moveNode() и добавьте connectedMoveCallback() в каждый пользовательский элемент, логика инициализации которого не должна повторно выполняться при смене его позиции.

Часто задаваемые вопросы

Может ли moveBefore() перемещать элемент в shadow root или из него?

Да. ShadowRoot наследуется от DocumentFragment, поэтому у него есть собственный метод moveBefore(). Перемещение должно происходить в пределах одного и того же shadow-including root, и подключённый shadow root удовлетворяет этому требованию для любого узла, подключённого к тому же документу. При перемещении содержимого light DOM в подключённое теневое дерево сохраняются фокус, состояние загрузки iframe и другие состояния, перечисленные в MDN.

Почему moveBefore() выбрасывает исключение, когда я вставляю только что созданный элемент?

Элемент, созданный через document.createElement(), ещё не подключён к документу. Перемещение отключённого узла в подключённый родитель выбрасывает HierarchyRequestError. Для первой вставки используйте appendChild() или insertBefore(). У узла, который ещё ни разу не был подключён, нет состояния iframe, фокуса или анимаций, которое нужно сохранять, поэтому ничего не теряется. Используйте moveBefore() только для последующих перемещений.

Можно ли сделать полифил moveBefore() для Safari?

Нет. Полифил может добавить метод moveBefore(), вызывающий insertBefore(), но это лишь копирует название метода. Сохранение документов iframe, фокуса, анимаций и открытых всплывающих элементов во время перемещения обеспечивает движок браузера, и JavaScript этого сделать не может. В браузерах без нативной поддержки такой шим ведёт себя точно так же, как insertBefore(), и сбрасывает то же самое состояние.

Используют ли moveBefore() какие-либо библиотеки?

Да. В htmx поддержка moveBefore() появилась в версии 2.0.3, выпущенной в октябре 2024 года. Если браузер предоставляет moveBefore(), htmx использует его для перемещения элементов с атрибутом hx-preserve при замене контента, благодаря чему эти элементы сохраняют своё состояние. В браузерах без этого метода htmx возвращается к обычному поведению и перемещает элементы старым способом — через удаление и вставку.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.