Document : méthode importNode()
Baseline
Widely available
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.
La méthode importNode() de l'interface Document crée une copie d'un nœud (Node) ou d'un DocumentFragment provenant d'un autre document, à insérer ultérieurement dans le document courant.
Le nœud importé n'est pas encore inclus dans l'arbre du document. Pour l'inclure, vous devez appeler une méthode d'insertion telle que appendChild() ou insertBefore() avec un nœud qui est déjà dans l'arbre du document.
Contrairement à document.adoptNode(), le nœud d'origine n'est pas supprimé de son document d'origine. Le nœud importé est un clone de l'original.
La méthode Node.cloneNode() crée également une copie d'un nœud. La différence est que importNode() clone le nœud dans le contexte du document appelant, tandis que cloneNode() utilise le document du nœud cloné. Le contexte du document détermine le CustomElementRegistry pour la construction de tout élément personnalisé. Pour cette raison, pour cloner des nœuds à utiliser dans un autre document, utilisez importNode() sur le document cible. Le HTMLTemplateElement.content appartient à un document séparé, il doit donc aussi être cloné avec document.importNode() afin que les descendants d'éléments personnalisés soient construits à partir des définitions du document courant. Voir les exemples de la page Node.cloneNode() pour plus de détails.
Syntaxe
importNode(externalNode)
importNode(externalNode, deep)
Paramètres
externalNode-
Le nœud (
Node) ou unDocumentFragmentexterne à importer dans le document courant. deepFacultatif-
Un indicateur booléen, dont la valeur par défaut est
false, qui contrôle s'il faut inclure toute la sous-arborescence DOM deexternalNodelors de l'importation.- Si
deepest défini àtrue, alorsexternalNodeet tous ses descendants sont copiés. - Si
deepest défini àfalse, alors seulexternalNodeest importé — le nouveau nœud n'a pas d'enfants.
- Si
Valeur de retour
Le importedNode copié dans le contexte du document importateur.
Note :
Le nœud parent (Node.parentNode) de importedNode est null, car il n'a pas encore été inséré dans l'arbre du document !
Exemples
Utiliser la méthode importNode()
const iframe = document.querySelector("iframe");
const ancienNoeud = iframe.contentWindow.document.getElementById("myNode");
const nouveauNoeud = document.importNode(ancienNoeud, true);
document.getElementById("container").appendChild(nouveauNoeud);
Notes
Avant de pouvoir être insérés dans le document courant, les nœuds provenant de documents externes doivent être :
- clonés à l'aide de
document.importNode(); ou - adoptés à l'aide de
document.adoptNode().
Note : Bien que Firefox n'applique pas actuellement cette règle, il est recommandé de la suivre pour une meilleure compatibilité future.
Pour en savoir plus sur les problèmes liés à Node.ownerDocument, consultez la FAQ DOM du W3C.
Spécifications
| Specification |
|---|
| DOM # ref-for-dom-document-importnode① |
Compatibilité des navigateurs
Voir aussi
- La méthode
document.adoptNode(), qui se comporte de manière très similaire à cette méthode - La méthode
Node.appendChild() - La méthode
Node.insertBefore()