Document.importNode()‎

يُنشئ التّابع Document.importNode()‎ نسخةً جديدةً من العقدة Node أو قطعة المُستند DocumentFragment المُحدّدة من مستندٍ آخر ليُمكِنَ إدخالها إلى المستند الحاليّ. لكنّها لا تُدخل إلى شجرة المُستند، لفعل ذلك، عليك استدعاء تابع مثل Node.appendChild()‎ أو Node.insertBefore()‎.

البنية العامة

var node = document.importNode(externalNode, deep);

القيم

externalNode‎

الكائن الجديد من النّوع Node أو DocumentFragment المرغوب استيراده إلى المستند الحالي. قيمة الخاصيّة parentNode الخاصّة بالعقدة الجديدة تكون null لأنّ العقدة لم تُدخل بعدُ إلى شجرة المستند.

deep‎

قيمةٌ منطقيّة من النّوع Boolean تُشير إلى ما إذا كان الاستيراد سيشمل كامل شجرة DOM الفرعيّة بدايةً بالعقدة الخارجيّة externalNode. إن كانت قيمة هذا المعامل true فسيكون النّسخ عميقًا، أي ستُنسخ العقدة الخارجيّة وجميع أولادها؛ أمّا إن كانت قيمته false، فستُستورَد العقدة externalNode وحدها.

مُلاحظة: يُعدّ المعامل deep مُعاملًا اختياريّا في مواصفة DOM4. وعند عدم تمريره، فالقيمة الافتراضيّة تكون true. ما يجعل النّسخَ عميقًا افتراضيًّا، ولتجنّب ذلك، لا بدّ من ضبط القيمة false للمُعامل deep. تغيّر هذا الأمر في المواصفة الأخيرة، وعند عدم تمرير التّابع، فالقيمة الافتراضيّة تكون false عكس ما سبق. ورغم أنّ المعامل اختياريّ، إلا أنّ عليك دائمًا تمرير قيمة له للحفاظ على التّوافقيّة.

أمثلة

var iframe = document.getElementsByTagName("iframe")[0];
var oldNode = iframe.contentWindow.document.getElementById("myNode");
var newNode = document.importNode(oldNode, true);
document.getElementById("container").appendChild(newNode);

ملاحظات

لا تُحذف العقدة الأصليّة من المُستند الأصليّ. والعقدة المُستورَدة نُسخةٌ من الأصليّة.

يجب نسخ العقد من المُستندات الخارجيّة باستخدام التّابع document.importNode()‎ أو تبنّيها بالتّابع document.adoptNode()‎ قبل إمكان إدخالها إلى المُستند الحاليّ. للاستزادة حول مشاكل ownerDocument انظر الأسئلة الشّائعة على W3C DOM.

لا يُلزِم مُتصفّح Firefox على العمل بهذه القاعدة (لأنّ الإلزام بها عطّل بعض المواقع). وإنما يُشجّع مطوّري الويب على إصلاح الشيفرة الخاصّة بهم لاتّباع هذه القاعدة لتوافقيّةٍ مُستقبليّةٍ أفضل.

دعم المتصفحات

الميزة	Chrome	Internet Explorer	Edge	Firefox	Opera	Safari
نسخة DOM 2	نعم	9	نعم	1	9	نعم
نسخة DOM 4 (المُعامل deep اختياريّ)	نعم	لا	نعم	10	لا	؟

انظر أيضًا

• Node.insertBefore()‎
• Node.hasChildNodes()‎
• Document.adoptNode()‎

مصادر ومواصفات

• مواصفة DOM
• مواصفة Document Object Model (DOM) Level 2 Core Specification