12k
All articles

Déplacer des nœuds DOM sans perdre leur état

Voyez comment Element.moveBefore() préserve l’état des iframes, du focus, des animations et des dialogues lors du déplacement de nœuds DOM, avec syntaxe et solutions de repli.

OpenReplay Team
OpenReplay Team
Déplacer des nœuds DOM sans perdre leur état

Element.moveBefore() déplace un nœud déjà présent dans le document sans passer par l’étape de suppression puis de réinsertion qu’effectuent appendChild() et insertBefore(). Une <iframe> conserve ainsi la page chargée, un champ qui a le focus le garde, et une animation CSS en cours continue de s’exécuter.

La plupart des développeurs qui changent le parent d’éléments actifs ont déjà rencontré ce problème : vous faites glisser une carte vers une nouvelle colonne, et le lecteur intégré qu’elle contient devient vide puis se recharge. Ou bien le champ dans lequel vous étiez en train de saisir du texte perd le focus au milieu d’un mot.

Chrome a livré moveBefore() dans Chrome 133, et la fonctionnalité figure dans les notes de version de Chrome 133 sous le nom « DOM state-preserving move ». Cet article présente la syntaxe, une démo, la liste exacte des états préservés, les cas d’erreur, les hooks des custom elements et une solution de repli sûre. Pour revoir d’abord les bases, consultez travailler avec le DOM en JavaScript et le cycle de vie des éléments du DOM.

Points clés à retenir

  • parent.moveBefore(node, ref) prend les mêmes arguments que insertBefore(), mais déplace le nœud sans le supprimer ni le réinsérer. Les iframes, le focus, les animations, les popovers et les boîtes de dialogue modales conservent donc leur état.
  • Le nœud déplacé doit être un nœud Element ou CharacterData. Les déplacements entre documents, entre arbres connectés et déconnectés, ou vers un descendant du nœud lui-même lèvent une HierarchyRequestError.
  • Un MutationObserver voit toujours un déplacement effectué avec moveBefore() comme une suppression suivie d’un ajout.
  • Les custom elements qui définissent connectedMoveCallback() reçoivent ce callback à la place de disconnectedCallback() et connectedCallback().
  • Safari ne prend pas en charge moveBefore(). Vérifiez donc 'moveBefore' in Element.prototype et rabattez-vous sur insertBefore() si nécessaire.

Pourquoi appendChild et insertBefore réinitialisent-ils l’état ?

Chaque déplacement effectué avec appendChild() ou insertBefore() correspond en réalité à deux opérations : le navigateur retire le nœud du document, puis l’insère à nouveau. L’article de lancement de l’équipe Chrome souligne que, depuis ses premiers standards, le DOM n’a jamais proposé d’autre moyen de déplacer un nœud. Or, retirer un nœud détruit l’état qui n’existe que tant que ce nœud est connecté. Une iframe décharge puis recharge son document, un élément qui a le focus le perd, les animations CSS redémarrent depuis le début, et les popovers ouverts ainsi que les boîtes de dialogue modales se ferment.

Dans les replays de session de tableaux de bord réorganisables, le bug se manifeste généralement ainsi : l’utilisateur fait glisser une carte et continue de taper, mais ses frappes ne sont pas prises en compte, car le champ a perdu le focus. Les iframes intégrées se rechargent visiblement en pleine session.

Syntaxe de moveBefore()

moveBefore() prend les deux mêmes arguments que insertBefore() : le nœud à déplacer et un nœud de référence. Si vous passez null comme référence, le nœud est déplacé à la fin des enfants du parent.

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

D’après la référence MDN de moveBefore(), le nœud déplacé doit être un nœud Element ou CharacterData. Les nœuds texte sont autorisés, mais pas les types de document, par exemple. La méthode existe également sur Document et DocumentFragment. Vous pouvez donc déplacer des nœuds à l’intérieur d’un fragment, même si un fragment n’est jamais connecté au document. La méthode est définie dans le DOM Living Standard.

Démo : déplacer une iframe avec et sans moveBefore

Le moyen le plus rapide de constater la différence consiste à utiliser une iframe dotée de son propre état interne. Cette démo utilise srcdoc et n’effectue donc aucune requête réseau.

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

Cliquez plusieurs fois sur le compteur à l’intérieur de l’iframe, puis essayez chacun des boutons. insertBefore() recharge l’iframe et le compteur revient à zéro. moveBefore(), lui, conserve la valeur. Le second bouton ne fonctionne que dans un navigateur qui prend en charge la méthode (voir la section sur la détection de fonctionnalité ci-dessous).

Le focus se comporte de la même manière :

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

Quels états moveBefore() préserve-t-il ?

moveBefore() conserve un ensemble précis d’états, listés sur MDN, et non tous les états possibles :

  • l’état des animations et des transitions ;
  • l’état de chargement des <iframe> ;
  • :focus et :active ;
  • l’état d’un élément en plein écran ;
  • l’état d’ouverture des popovers ;
  • l’état des <dialog> modales.

Les éléments natifs <video> et <audio> conservent leur état de lecture, même lorsqu’ils sont déplacés avec appendChild() ou insertBefore(). Pour les médias, moveBefore() est donc utile lorsque le lecteur est intégré dans une <iframe>, comme une vidéo tierce embarquée, et non pour les éléments multimédias natifs.

Erreurs et contraintes de moveBefore()

moveBefore() est plus strict qu’insertBefore(). Il lève une exception dans des cas où insertBefore() effectuerait discrètement une suppression suivie d’une insertion.

ErreurDéclenchée lorsqueQue faire
HierarchyRequestErrorLe déplacement a lieu entre un arbre connecté et un arbre déconnectéUtiliser insertBefore()
HierarchyRequestErrorLe déplacement a lieu entre deux documentsUtiliser insertBefore() (ou adoptNode() au préalable)
HierarchyRequestErrorUn nœud est déplacé dans l’un de ses propres descendantsCorriger la cible : il s’agit d’un bug de logique
HierarchyRequestErrormovedNode n’est ni un Element ni un CharacterDataUtiliser insertBefore()
NotFoundErrorreferenceNode n’est pas un enfant du parentPasser un véritable enfant ou null
TypeErrorLe second argument est absentPasser explicitement null pour ajouter en fin de liste

La ligne TypeError piège souvent les développeurs, car les réflexes acquis avec insertBefore() persistent : vous ne pouvez pas ajouter un nœud en fin de liste en appelant moveBefore(node) avec un seul argument.

MutationObserver et connectedMoveCallback

Un MutationObserver enregistre toujours un nœud déplacé avec moveBefore() comme un nœud supprimé et un nœud ajouté. Les observers existants continuent donc de recevoir des enregistrements lors des déplacements. Les étapes de déplacement du DOM Standard placent en file d’attente un enregistrement de suppression pour l’ancien parent et un enregistrement d’ajout pour le nouveau. Si votre code considère une suppression comme une « destruction », il lui faut un autre signal pour distinguer les déplacements des suppressions. Pour la configuration des observers, consultez les trois API d’observation du DOM.

Les custom elements disposent d’un hook dédié aux déplacements : connectedMoveCallback(). Comme l’explique le guide MDN sur les custom elements, lorsque connectedMoveCallback() est défini, il est appelé à la place de connectedCallback() et disconnectedCallback() chaque fois que l’élément est déplacé à un autre endroit du DOM via 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);

Si la classe ne définit pas connectedMoveCallback(), un déplacement via moveBefore() exécute toujours disconnectedCallback() puis connectedCallback(). Définir la méthode, même sous la forme d’une fonction vide, remplace cette paire d’appels. Ce comportement est décrit dans la spécification HTML.

Détection de fonctionnalité et solution de repli pour moveBefore

Vérifiez 'moveBefore' in Element.prototype avant d’appeler la méthode. Rabattez-vous sur insertBefore() lorsque la méthode est absente, mais aussi lorsqu’elle lève une HierarchyRequestError pour un déplacement qu’insertBefore() accepterait. D’après caniuse, Chrome et Edge 133+ ainsi que Firefox 144+ la prennent en charge, ce qui n’est pas le cas de Safari. web-features la classe en disponibilité limitée (Limited availability) et non en 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();
}

La solution de repli basée sur insertBefore() recharge toujours les iframes, redémarre les animations et ferme les boîtes de dialogue, exactement comme insertBefore() l’a toujours fait. La restauration du focus se contente de redonner le focus à l’élément : la position du curseur n’est pas garantie. Cette vérification ne couvre que les parents de type Element. Elle n’indique pas si Document ou DocumentFragment prennent en charge la méthode.

Conclusion

moveBefore() dote enfin le DOM d’un véritable déplacement : un seul appel suffit pour que les iframes restent chargées, que le focus reste en place et que les animations continuent de s’exécuter, à condition de respecter les contraintes listées par MDN. Repérez chaque appel à appendChild() ou insertBefore() qui déplace un nœud actif dans votre code de glisser-déposer ou de morphing, faites-le passer par un helper comme moveNode(), et ajoutez connectedMoveCallback() à tout custom element dont l’initialisation ne doit pas être relancée lorsqu’il est repositionné.

FAQ

moveBefore() peut-il déplacer un élément vers ou depuis une shadow root ?

Oui. ShadowRoot hérite de DocumentFragment et dispose donc de sa propre méthode moveBefore(). Le déplacement doit rester au sein de la même racine incluant les shadow roots (shadow-including root), et une shadow root connectée remplit cette condition pour tout nœud connecté au même document. Déplacer du contenu du light DOM vers un shadow tree connecté conserve le focus, l'état de chargement des iframes et les autres états listés par MDN.

Pourquoi moveBefore() lève-t-il une exception lorsque j'insère un élément nouvellement créé ?

Un élément créé avec document.createElement() n'est pas encore connecté au document. Déplacer un nœud déconnecté vers un parent connecté lève une HierarchyRequestError. Utilisez appendChild() ou insertBefore() pour la première insertion. Un nœud qui n'a jamais été connecté n'a ni iframe, ni focus, ni état d'animation à conserver : rien n'est donc perdu. Réservez moveBefore() aux déplacements ultérieurs.

Peut-on créer un polyfill de moveBefore() pour Safari ?

Non. Un polyfill peut ajouter une méthode moveBefore() qui appelle insertBefore(), mais il ne reproduit que le nom de la méthode. C'est le moteur du navigateur qui maintient en vie les documents des iframes, le focus, les animations et les popovers ouverts pendant le déplacement, et JavaScript ne peut pas le faire. Dans les navigateurs sans prise en charge native, un shim se comporte exactement comme insertBefore() et réinitialise les mêmes états.

Des bibliothèques utilisent-elles déjà moveBefore() ?

Oui. htmx a ajouté la prise en charge de moveBefore() dans sa version 2.0.3, publiée en octobre 2024. Lorsque le navigateur expose moveBefore(), htmx l'utilise pour déplacer les éléments marqués avec hx-preserve lors des remplacements de contenu, afin qu'ils conservent leur état. Dans les navigateurs dépourvus de la méthode, htmx revient à son comportement habituel, qui déplace les éléments à l'ancienne, par suppression puis insertion.

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.