Document : méthode moveBefore()

Limited availability

Cette fonctionnalité n'est pas Compatible car elle ne fonctionne pas dans certains des navigateurs les plus utilisés.

La méthode moveBefore() de l'interface Document déplace un nœud (Node) donné à l'intérieur du nœud DOM Document en tant qu'enfant direct, avant un nœud de référence donné.

Syntaxe

moveBefore(movedNode, referenceNode)

Paramètres

movedNode: Un nœud (Node) représentant le nœud à déplacer. Notez que cela doit être un nœud Element ou CharacterData.
referenceNode: Un nœud (Node) avant lequel movedNode sera déplacé, ou null. Si la valeur est null, movedNode est inséré à la fin des nœuds enfants du Document.

Exceptions

HierarchyRequestError TypeError

Levée dans l'une des situations suivantes :

Le nœud à déplacer (movedNode) défini n'est pas partie de ce document.
Le nœud à déplacer (movedNode) défini n'est pas un nœud de type Element ou CharacterData.
Vous essayez de déplacer movedNode avant le doctype du document (représenté par un objet DocumentType).

NotFoundError TypeError

Le nœud de référence (referenceNode) défini n'est pas un enfant du nœud sur lequel vous appelez moveBefore(), c'est-à-dire le nœud dans lequel vous essayez de déplacer movedNode.

TypeError TypeError

Le deuxième argument n'a pas été fourni.

La méthode moveBefore() déplace un nœud donné vers un nouvel emplacement dans le DOM. Elle offre une fonctionnalité similaire à la méthode Node.insertBefore(), sauf qu'elle ne supprime pas puis ne réinsère pas le nœud. Cela signifie que l'état du nœud (qui serait réinitialisé si on le déplaçait avec insertBefore() et des mécanismes similaires) est préservé après le déplacement. Cela inclut :

L'état des animations et des transitions CSS.
L'état de chargement de l'élément HTML <iframe>.
Les états d'interactivité (par exemple, les pseudos-classes CSS :focus et :active).
L'état de plein écran d'un élément.
L'état ouvert/fermé des fenêtres contextuelles.
L'état des boîtes de dialogues (modal en anglais) de l'élément HTML <dialog> (les boîtes de dialogues ne seront pas fermées).

L'état de lecture des éléments HTML <video> et <audio> n'est pas inclus dans la liste ci-dessus, car ces éléments conservent leur état lorsqu'ils sont retirés et réinsérés, quel que soit le mécanisme utilisé.

Lors de l'observation des modifications du DOM à l'aide d'un objet MutationObserver, les nœuds déplacés avec moveBefore() seront enregistrés avec un nœud supprimé et un nœud ajouté.

La méthode moveBefore() n'est pas particulièrement utile lorsqu'elle est invoquée sur le nœud Document. Il existe quelques utilisations non élémentaires pour celle-ci, par exemple, vous pourriez utiliser moveBefore() pour déplacer des nœuds de commentaire autour de la racine du Document. Cependant, vous êtes beaucoup plus susceptible de trouver une utilisation pour l'invoquer sur un objet DocumentFragment ou un Element individuel — voir DocumentFragment.moveBefore() et Element.moveBefore().

Contraintes de `moveBefore()`

Il existe certaines contraintes à prendre en compte lors de l'utilisation de moveBefore() :

Ça ne fonctionne que lorsque l'on déplace un nœud au sein du même document.
Ça ne fonctionnera pas si vous essayez de déplacer un nœud qui n'est pas connecté au DOM vers un parent déjà connecté, ou vice versa.

Dans de tels cas, moveBefore() échouera avec une exception HierarchyRequestError. Si les contraintes ci-dessus sont des exigences pour votre cas d'utilisation particulier, vous devriez utiliser Node.insertBefore() à la place, ou utiliser try…catch pour gérer les erreurs qui surviennent dans de tels cas.

Exemples

Déplacer un nœud de commentaire avec `moveBefore()`

Dans cette démonstration, nous montrons comment utiliser document.moveBefore() pour déplacer un nœud de commentaire dans le DOM.

HTML

Le HTML est un modèle minimal qui contient un commentaire à l'intérieur de l'élément HTML <body>.

html

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <title>Exemple document.moveBefore()</title>
  </head>
  <body>
    <!-- Ce commentaire devrait être à la fin du document -->
    <p>Du contenu</p>
  </body>
</html>

JavaScript

Dans notre script, nous parcourons tous les nœuds enfants (childNodes) de l'élément <body>. Lorsque nous trouvons un nœud avec une valeur nodeType de 8 (ce qui indique un nœud de commentaire), nous stockons une référence à celui-ci dans une variable appelée noeudCommentaire. Nous invoquons ensuite document.moveBefore(), en définissant que nous voulons déplacer le nœud de commentaire, et en définissant un deuxième argument de null pour insérer notre commentaire à la fin des nœuds enfants du Document.

let noeudCommentaire;

for (noeud of document.querySelector("body").childNodes) {
  if (noeud.nodeType === 8) {
    noeudCommentaire = noeud;
  }
}

document.moveBefore(noeudCommentaire, null);

Résultat

L'exemple rendu ressemble à ceci :

Si vous inspectez l'exemple avec les outils de développement de votre navigateur, vous remarquerez que le commentaire a été déplacé à la fin du document, après la balise de fermeture </html>.