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>. Document.createElementNS()Node.removeChild()Node.replaceChild()Node.appendChild()Node.insertBefore()Node.hasChildNodes()Document.createElementNS()لتحديد عنوان URI الخاصّ بمجال الأسماء صراحةً (explicitly) للعنصر.- مواصفة DOM
// أنشئ صنفًا للعنصر
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 | ؟ | ؟ |