Document.getElementById()
يُعيد التّابع Document.getElementById() كائنًا من النّوع Element يُمثّل العنصر ذو المُعرّف (id) الذي يُوافق السلسلة النّصيّة المُحدّدة. ولأنّ مُعرّفات العناصر لا بدّ لها أن تكون فريدة عند إنشائها، فهي مُفيدة للوصول إلى عنصرٍ مُعيّنٍ بسرعة.
إن أردت الوصول إلى عنصر لا يملك مُعرّفًا، يُمكنك استعمال التّابع querySelector() للوصول إلى العنصر بأيّ مُحدِّدٍ كيفما كان.
البنية العامة
var element = document.getElementById(id);
القيم
element
كائنٌ من النّوع Element يُمثّل عنصر DOM الذي يوافق مُعرّفه المُعرّف المُعطى، أو القيمة null في حالة لم يوجد عنصر موافقٌ في المستند.
id
مُعرّف العنصر المرغوب إيجاده. المُعرّف سلسلةٌ نصيّةٌ حسّاسةٌ لحالة الأحرف (case-sensitive) ويكون فريدًا في المُستند؛ لا يُمكن إلّا لعنصرٍ واحدٍ فقط أن يحمل مُعرّفًا مُحدّدًا.
أمثلة
المثال الأول
جزء HTML:
<html>
<head>
<title>getElementById example</title>
</head>
<body>
<p id="para">Some text here</p>
<button onclick="changeColor('blue');">blue</button>
<button onclick="changeColor('red');">red</button>
</body>
</html>
جزء JavaScript:
function changeColor(newColor) {
var elem = document.getElementById('para');
elem.style.color = newColor;
}
المثال الثّاني
<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<title>Document</title>
</head>
<body>
<div id="parent-id">
<p>hello word1</p>
<p id="test1">hello word2</p>
<p>hello word3</p>
<p>hello word4</p>
</div>
<script>
var parentDOM = document.getElementById('parent-id');
var test1=parentDOM.getElementById('test1');
//يرمي الخطأ
//Uncaught TypeError: parentDOM.getElementById is not a function
</script>
</body>
</html>
تُعاد القيمة null في حالة لم يوجد عنصر موافقٌ للمُعرّف id المُعطى. لاحظ أنّ المعامل id حسّاس لحالة الأحرف، لذا فالاستدعاء Document.getElementById("Main") يعيد القيمة null عوضًا عن العنصر <div id="main"> لأنّ "M" و "m" قيمتان مُختلفتان عند التّعامل مع هذا التّابع.
لا يُبحث عن العناصِر غير الموجودة على المُستند من طرف التّابع Document.getElementById(). عند إنشاء عنصرٍ وتعيين قيمة مُعرّف له، يجب عليك إدخال العنصر إلى المستند عبر التّابع Node.insertBefore() أو تابع مُشابهٍ قبل أن تتمكّن من الوصول إليه عبر التّابع Document.getElementById():
var element = document.createElement('div');
element.id = 'testqq';
var el = document.getElementById('testqq'); // el سيُساوي null
مُلاحظة حول المُستندات المُغايرة لمُستندات HTML: يجب على تطبيق DOM أن يحتوي معلومات تُخبر عن أيّ الخصائصِ هي من النّوع ID. الخصائصِ ذات الاسم "id" ليست مُعرّفات إلا عند تعريف ذلك في DTD الخاصّ بالمستند. الخاصيّة "id" مُعرّفة بأنّها من النّوع ID في المُستندات المعروفة مثل XHTML وXUL وغيرها. لا يُتوقَّع من التّطبيقات التي لا تعرف ما إذا كانت الخصائص من النّوع ID أو لا ان تُعيد القيمة null.
ملاحظات
يجب على حالة الأحرف في هذا التّابع أن تكون صحيحة، لن يعمل التّابع Document.getElementByID() ولا التّابع Document.getElementByid()، إذ يجب أن توافق حالة الأحرف ما في التّابع Document.getElementById().
على النّقيض من بعض التّوابع الأخرى التي تبحث عن العناصِر في الصّفحة مثل querySelector() وquerySelectorAll()، فالتّابع getElementById() مُتاح فقط كتابع للكائن document العمومي، وليس مُتاحًا كتابعٍ على جميع كائنات العناصر في DOM. وذلك لأنّ قيم المُعرّفات لا بدّ لها وأن تكون فريدةً على كامل المُستند، ولا حاجة لنُسخٍ محليّة للتّابع.
دعم المتصفحات
| الميزة | Chrome | Firefox | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| الدعم الأساسي | 1 | 1 | 5.5 | 7 | 1 |
انظر أيضًا
Documentمرجعٌ لتوابع وخصائص أخرى للتّعامل مع العناصر في المستند.Document.querySelector()لاستعمال المُحدِّدات التي تستعمل استعلامات مثل'div.myclass'.