12k
All articles

Movendo nós do DOM sem perder o estado

Veja como Element.moveBefore() preserva o estado de iframes, foco, animações e diálogos ao mover nós DOM, com sintaxe, restrições e alternativas.

OpenReplay Team
OpenReplay Team
Movendo nós do DOM sem perder o estado

Element.moveBefore() move um nó que já está no documento sem a etapa de remover e reinserir que appendChild() e insertBefore() executam. Assim, um <iframe> mantém a página carregada, um input com foco continua focado e uma animação CSS em andamento segue rodando.

A maioria dos desenvolvedores que já reposicionou elementos ativos na árvore passou por isto: você arrasta um card para outra coluna e o player incorporado dentro dele fica em branco e recarrega, ou o campo em que você estava digitando perde o foco no meio de uma palavra.

O Chrome lançou o moveBefore() no Chrome 133, e o recurso aparece nas notas de versão do Chrome 133 como “DOM state-preserving move”. Este artigo aborda a sintaxe, uma demonstração, a lista exata dos estados preservados, os casos de erro, os hooks de custom elements e um fallback seguro. Se você precisar revisar o básico antes, consulte trabalhando com o DOM em JavaScript e o ciclo de vida dos elementos do DOM.

Principais conclusões

  • parent.moveBefore(node, ref) recebe os mesmos argumentos que insertBefore(), mas move o nó sem removê-lo e reinseri-lo, de modo que iframes, foco, animações, popovers e diálogos modais mantêm seu estado.
  • O nó movido precisa ser um nó Element ou CharacterData. Movimentações entre documentos, entre árvores conectadas e desconectadas ou para dentro de um descendente do próprio nó lançam HierarchyRequestError.
  • Um MutationObserver ainda enxerga uma movimentação feita com moveBefore() como uma remoção e uma adição.
  • Custom elements que definem connectedMoveCallback() recebem esse callback em vez de disconnectedCallback() e connectedCallback().
  • O Safari não oferece suporte a moveBefore(), então verifique 'moveBefore' in Element.prototype e use insertBefore() como fallback.

Por que appendChild e insertBefore redefinem o estado?

Toda movimentação feita com appendChild() ou insertBefore() na verdade são duas operações: o navegador remove o nó do documento e depois o insere novamente. O post de lançamento da equipe do Chrome destaca que, desde os primeiros padrões, o DOM não tinha outra forma de mover um nó. Remover um nó destrói o estado que só existe enquanto o nó está conectado. Um iframe descarrega e recarrega seu documento, um elemento focado perde o foco, as animações CSS recomeçam do início e popovers e diálogos modais abertos são fechados.

Em session replays de dashboards reordenáveis, o bug costuma se manifestar assim: o usuário arrasta um card, continua digitando e as teclas não chegam ao destino porque o campo perdeu o foco. Iframes incorporados recarregam visivelmente no meio da sessão.

Sintaxe do moveBefore()

moveBefore() recebe os mesmos dois argumentos que insertBefore(): o nó a ser movido e um nó de referência. Passar null como referência move o nó para o final dos filhos do elemento pai.

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

De acordo com a referência do moveBefore() no MDN, o nó movido precisa ser um nó Element ou CharacterData. Nós de texto são permitidos, mas tipos de documento, por exemplo, não são. O método também existe em Document e em DocumentFragment, então você pode mover nós dentro de um fragment, mesmo que um fragment nunca esteja conectado ao documento. O método é definido no DOM Living Standard.

Demonstração: movendo um iframe com e sem moveBefore

A forma mais rápida de ver a diferença é usar um iframe com estado interno próprio. Esta demonstração usa srcdoc, portanto não faz nenhuma requisição de rede.

<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>

Clique algumas vezes no contador dentro do frame e depois teste cada botão. insertBefore() recarrega o frame e o contador volta a zero. moveBefore() mantém a contagem. O segundo botão só funciona em navegadores que oferecem suporte ao método (veja a seção sobre detecção de recurso mais abaixo).

O foco se comporta da mesma forma:

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

Quais estados o moveBefore() preserva?

moveBefore() mantém um conjunto específico de estados, listados no MDN. Ele não preserva todos os estados possíveis:

  • Estado de animações e transições
  • Estado de carregamento do <iframe>
  • :focus e :active
  • Estado de elemento em tela cheia (fullscreen)
  • Estado aberto de popovers
  • Estado de <dialog> modal

Elementos nativos <video> e <audio> mantêm o estado de reprodução mesmo quando movidos com appendChild() ou insertBefore(). Portanto, no caso de mídia, o moveBefore() faz diferença quando o player está incorporado em um <iframe>, como um embed de vídeo de terceiros, e não para elementos de mídia nativos.

Erros e restrições do moveBefore()

moveBefore() é mais rigoroso que insertBefore(). Ele lança exceções em casos nos quais insertBefore() faria silenciosamente uma remoção seguida de inserção.

ErroDisparado quandoO que fazer
HierarchyRequestErrorMovimentação entre uma árvore conectada e uma desconectadaUse insertBefore()
HierarchyRequestErrorMovimentação entre documentosUse insertBefore() (ou adoptNode() antes)
HierarchyRequestErrorMovimentação de um nó para dentro de seu próprio descendenteCorrija o destino: é um bug de lógica
HierarchyRequestErrormovedNode não é um Element nem CharacterDataUse insertBefore()
NotFoundErrorreferenceNode não é filho do elemento paiPasse um filho real ou null
TypeErrorO segundo argumento está ausentePasse null explicitamente para adicionar ao final

A linha do TypeError pega muita gente desprevenida, porque os hábitos do insertBefore() acabam sendo transferidos: não é possível adicionar ao final chamando moveBefore(node) com apenas um argumento.

MutationObserver e connectedMoveCallback

Um MutationObserver continua registrando um nó movido com moveBefore() como um nó removido e um nó adicionado, então os observers existentes seguem recebendo registros para movimentações. Os move steps do DOM Standard enfileiram um registro de remoção para o pai antigo e um registro de adição para o novo. Código que trata uma remoção como “destruído” precisa de outro sinal se tiver que diferenciar movimentações de exclusões. Para a configuração de observers, veja as três APIs de observers do DOM.

Custom elements ganham um hook dedicado para movimentação, o connectedMoveCallback(). Como explica o guia de custom elements do MDN, quando connectedMoveCallback() está definido, ele é chamado em vez de connectedCallback() e disconnectedCallback() sempre que o elemento é movido para outro lugar no DOM por meio de 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);

Se a classe não definir connectedMoveCallback(), uma movimentação com moveBefore() ainda executa disconnectedCallback() e depois connectedCallback(). Definir o método, mesmo como uma função vazia, substitui esse par. A especificação HTML descreve esse comportamento.

Detecção de recurso e fallback para moveBefore

Verifique 'moveBefore' in Element.prototype antes de chamar o método. Use insertBefore() como fallback quando o método não existir e também quando ele lançar um HierarchyRequestError em uma movimentação que insertBefore() aceitaria. Segundo o caniuse, Chrome e Edge 133+ e Firefox 144+ oferecem suporte, e o Safari não. O web-features classifica o recurso como Limited availability, e não como 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();
}

O fallback com insertBefore() continua recarregando iframes, reiniciando animações e fechando diálogos, exatamente como insertBefore() sempre fez. Restaurar o foco apenas devolve o foco ao elemento, e a posição do cursor de texto não é garantida. Essa verificação cobre apenas pais do tipo Element. Ela não informa se Document ou DocumentFragment oferecem suporte ao método.

Conclusão

moveBefore() dá ao DOM, pela primeira vez, uma movimentação de verdade: uma única chamada que mantém iframes carregados, o foco no lugar e animações em execução, desde que você respeite as restrições listadas no MDN. Encontre todas as chamadas a appendChild() ou insertBefore() no seu código de drag-and-drop ou de morphing que movem um nó ativo, passe-as por um helper como moveNode() e adicione connectedMoveCallback() a qualquer custom element cuja inicialização não deva ser executada novamente quando ele for reposicionado.

Perguntas frequentes

O moveBefore() consegue mover um elemento para dentro ou para fora de uma shadow root?

Sim. ShadowRoot herda de DocumentFragment, portanto tem seu próprio método moveBefore(). A movimentação precisa permanecer dentro da mesma shadow-including root, e uma shadow root conectada atende a esse requisito para qualquer nó conectado ao mesmo documento. Mover conteúdo do light DOM para dentro de uma shadow tree conectada preserva o foco, o estado de carregamento de iframes e os demais estados listados no MDN.

Por que o moveBefore() lança uma exceção quando insiro um elemento recém-criado?

Um elemento criado com document.createElement() ainda não está conectado ao documento. Mover um nó desconectado para um pai conectado lança um HierarchyRequestError. Use appendChild() ou insertBefore() para a primeira inserção. Um nó que nunca foi conectado não tem estado de iframe, foco ou animação a preservar, então nada é perdido. Use moveBefore() apenas para as movimentações seguintes.

É possível criar um polyfill do moveBefore() para o Safari?

Não. Um polyfill pode adicionar um método moveBefore() que chama insertBefore(), mas isso apenas reproduz o nome do método. É o motor do navegador que mantém vivos os documentos de iframes, o foco, as animações e os popovers abertos durante a movimentação, e o JavaScript não consegue fazer isso. Em navegadores sem suporte nativo, um shim se comporta exatamente como insertBefore() e redefine os mesmos estados.

Alguma biblioteca já usa o moveBefore()?

Sim. O htmx adicionou suporte a moveBefore() na versão 2.0.3, lançada em outubro de 2024. Quando o navegador expõe moveBefore(), o htmx o utiliza para mover elementos marcados com hx-preserve durante as trocas de conteúdo, de modo que esses elementos mantêm seu estado. Em navegadores sem o método, o htmx volta ao comportamento normal, movendo os elementos da forma antiga, com remoção e inserção.

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.