Node : méthode appendChild()

Syntaxe

appendChild(child)

Paramètres

child

Le nœud à ajouter au nœud parent donné (généralement un élément).

Valeur de retour

Un Node qui est l'enfant ajouté (child), sauf lorsque child est un DocumentFragment, auquel cas le DocumentFragment vide est retourné.

Exceptions

HierarchyRequestError DOMException

Levée lorsque les contraintes de l'arbre DOM sont violées, c'est-à-dire si l'un des cas suivants se produit :

• Si le parent de child n'est pas un objet Document, un objet DocumentFragment ou un objet Element.
• Si l'insertion de child entraîne un cycle, c'est-à-dire si child est un ancêtre du nœud.
• Si child n'est pas un objet DocumentFragment, un objet DocumentType, un objet Element, ou un objet CharacterData.
• Si le nœud actuel est un objet Text, et que son parent est un objet Document.
• Si le nœud actuel est un objet DocumentType et que son parent n'est pas un objet Document, car un doctype doit toujours être un descendant direct d'un document.
• Si le parent du nœud est un objet Document et que child est un objet DocumentFragment avec plus d'un enfant Element, ou qui a un enfant Text.
• Si l'insertion de child entraîne un objet Document avec plus d'un enfant Element.

Description

Si l'enfant donné est une référence à un nœud existant dans le document, appendChild() le déplace de sa position actuelle à la nouvelle position — il n'est pas nécessaire de retirer le nœud de son parent avant de l'ajouter à un autre nœud. Cela signifie qu'un nœud ne peut pas être à deux endroits du document simultanément. La méthode Node.cloneNode() peut être utilisée pour créer une copie du nœud avant de l'ajouter sous le nouveau parent. Les copies créées avec cloneNode ne sont pas automatiquement synchronisées.

appendChild() retourne le nœud nouvellement ajouté, au lieu du nœud parent. Cela signifie que vous pouvez ajouter le nouveau nœud dès sa création sans perdre la référence à celui-ci :

const paragraphe = document.body.appendChild(document.createElement("p"));
// Vous pouvez ajouter d'autres éléments au paragraphe plus tard

D'un autre côté, vous ne pouvez pas utiliser appendChild() dans un style d'API fluide ^(angl.) (comme jQuery).

// Cela n'ajoute pas trois paragraphes :
// les trois éléments sont imbriqués au lieu d'être des voisins
document.body
  .appendChild(document.createElement("p"))
  .appendChild(document.createElement("p"))
  .appendChild(document.createElement("p"));

Exemples

Ajouter un paragraphe au corps du document

// Crée un nouvel élément paragraphe et l'ajoute à la fin du corps du document
const p = document.createElement("p");
document.body.appendChild(p);

Créer une structure DOM imbriquée

Dans cet exemple, nous essayons de créer une structure DOM imbriquée en utilisant le moins de variables temporaires possible.

const fragment = document.createDocumentFragment();
const li = fragment
  .appendChild(document.createElement("section"))
  .appendChild(document.createElement("ul"))
  .appendChild(document.createElement("li"));
li.textContent = "bonjour le monde";

document.body.appendChild(fragment);

Cela génère l'arbre DOM suivant :

<section>
  <ul>
    <li>bonjour le monde</li>
  </ul>
</section>

Spécifications

Compatibilité des navigateurs

Voir aussi

• La méthode Node.removeChild()
• La méthode Node.replaceChild()
• La méthode Node.insertBefore()
• La méthode Node.hasChildNodes()
• La méthode Element.insertAdjacentElement()
• La méthode Element.append()