Document.createElement()‎

من موسوعة حسوب
اذهب إلى: تصفح، ابحث

في مُستندات HTML، يُنشئُ التّابع Document.createElement()‎ عنصرَ HTML المُحدّد عبر المُعامل tagName الذي يُمثّل اسم الوسم، أو يُنشئ كائنا من النّوع HTMLUnknownElement إن لم يُتعرَّف على اسم الوسم tagName.

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

var element = document.createElement(tagName[, options]);

المعاملات

tagName

سلسلةٌ نصيّةٌ تُحدّد نوع العنصر المرغوب إنشاؤه. قيمة nodeName الخاصّة بالعنصر المُنشأ تُحدَّد من قيمة tagName. لا تَستعمِل الأسماء الموصوفة (مثل "html:a") مع هذا التّابع. عندما يُستدعى التّابع على مُستند HTML، فستُحوَّل قيمة tagName إلى أحرف صغيرة (lower case) قبل إنشاء العنصر. وفي معظم المُتصفّحات، التّعبير createElement(null)‎ مُكافئٌ للتّعبير createElement("null"‎)‎.

options

مُعاملٌ اختياريّ من النّوع ElementCreationOptions يحتوي على خاصيّة واحدة تُسمّى is، وقيمتها هي اسمُ الوسمِ لعنصرٍ مُخصّصٍ مُعرّفٍ مُسبقًا عبر التّابع customElements.define‎()‎‎. انظر مثال مكوّنات الويب أدناه للمزيد من التّفاصيل.

القيمة المعادة

الكائن الجديد من النّوع Element.

أمثلة

مثال بسيط

يُنشئ المثال التّالي عنصر <div> جديد ويُدخله قبل العنصر ذو المعرّف "div1".

في جزء HTML نضع:

<!DOCTYPE html>
<html>
<head>
  <title>التّعامل مع العناصر</title>
</head>
<body>
  <div id="div1">أُنشئ النّص أعلاه ديناميكيًّا</div>
</body>
</html>

في جزء JavaScript نضع:

document.body.onload = addElement;

function addElement () { 
  // أنشئ العنصر الجديد
  var newDiv = document.createElement("div"); 
  // ضَع محتوى داخل العنصر
  var newContent = document.createTextNode("مرحبًا"); 
  // أضف عقدة النّص إلى العنصر المُنشأ
  newDiv.appendChild(newContent);  

  // أضف العنصر الجديد ومحتوياته إلى 
  // DOM
  var currentDiv = document.getElementById("div1"); 
  document.body.insertBefore(newDiv, currentDiv); 
}

مثال مكونات الويب

المثال التّالي يوسّع العنصر HTMLUListElement الذي يُمثّل العنصرَ <ul>.
    // أنشئ صنفًا للعنصر
    class ExpandingList extends HTMLUListElement {
      constructor() {
        // استدعِ دائما هذه الدّالة في أول الدّالة البانيّة
        super();
    
        // تعريف الدّالة البانيّة مُتجاهلٌ لإيجاز المثال
        ...
      }
    }
    
    // عرّف العنصر الجديد
    customElements.define('expanding-list', ExpandingList, { extends: "ul" });
    

    لو أردنا إنشاء نسخةٍ (instance) من هذا العنصر برمجيًّا، لاستعملنا استدعاءً مُشابهًا لما يلي:

    let expandingList = document.createElement('ul', { is : 'expanding-list' })
    

    سيُعطى العنصر الجديد خاصيّة is قيمتها اسمُ وسم العنصرِ المُخصّص.

    مُلاحظة: لإبقاء التوافقيّة العكسيّة مع النّسخ السّابقة من مواصفة Custom Elements، ستسمح لك بعض المتصفحات بتمرير سلسلةٍ نصيّة عوضًا عن كائنٍ هنا، والذي تكون فيه قيمةُ السّلسلةِ النّصيّة اسمَ وسمِ العنصرِ المُخصّص.

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

    الميزة Chrome Internet Explorer Edge Firefox Opera Safari
    الدعم الأساسي نعم نعم نعم نعم نعم نعم
    المُعامل options نعم ؟ ؟ 50 ؟ ؟

    انظر أيضًا

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

    • مواصفة DOM