Document.getElementsByTagName()
يُعيد التّابع Document.getElementsByTagName() كائنًا من النّوع HTMLCollection يحتوي على جميع العناصر ذات اسم الوسم (tag name) المُعطى. عند استدعائه على كائن المُستند، فسيُبحَثُ في كامل المُستند، ما يشمل العقدة الجذر. القيمة المُعادة حيّة، أي أنّها تُحدّث نفسها تلقائيّا للبقاء مُتزامنةً مع شجرة DOM دون الحاجة إلى استدعاء التّابع Document.getElementsByTagName() مرّة أخرى.
البنية العامة
var elements = document.getElementsByTagName(name);
elements
كائنٌ حيّ من النّوع HTMLCollection (لكن انظر الملاحظات أدناه) يُمثّل مجموعة العناصِر التي وُجدت مرتّبةً حسب طريقة عرضها في شجرة DOM.
name
سلسلةٌ نصيّةٌ تُمثّل اسم العنصر. السلسلة النّصيّة الخاصّة "*" تُمثّل جميع العناصر.
مُلاحظة: تقول آخر مواصفة من W3C بأنّ قيمة elements عبارةٌ عن كائن HTMLCollection، لكنّ هذا التّابع يُعيد كائنا من النّوع NodeList في مُتصفّحات WebKit (مثل Chrome وSafari). انظر العلّة 14869 للمزيد من التّفاصيل.
أمثلة
يبدأ التّابع Document.getElementsByTagName() في المثال التّالي من عنصرٍ أبٍ معيّنٍ ويبحث من الأعلى إلى الأسفل تعاوديًّا (recursively) عبر DOM بدايةً من العنصر الأب، بانيًّا مجموعة عناصر أولاد يُساوي اسمها المُعامل name. هذا يشرح كلًّا من Document.getElementsByTagName() والتّابع المُشابه له Element.getElementsByTagName()، والذي يبدأ البحث من عنصرٍ مُعيّن داخل شجرة DOM.
الضّغط على الأزرار يستعمل التّابع getElementsByTagName() لحساب عدد عناصر الفقراتِ أولادِ أبٍ مُعيّن (إمّا المُستند نفسَه أو واحدا من عنصري <div> مُتداخلين).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>getElementsByTagName example</title>
<script>
function getAllParaElems() {
var allParas = document.getElementsByTagName('p');
var num = allParas.length;
alert('هناك' + num + ' فقرات في هذا المستند');
}
function div1ParaElems() {
var div1 = document.getElementById('div1');
var div1Paras = div1.getElementsByTagName('p');
var num = div1Paras.length;
alert('هناك' + num + ' فقرات في #div1');
}
function div2ParaElems() {
var div2 = document.getElementById('div2');
var div2Paras = div2.getElementsByTagName('p');
var num = div2Paras.length;
alert('هناك' + num + ' فقرات في #div2');
}
</script>
</head>
<body style="border: solid green 3px">
<p>نصّ خارجيّ</p>
<p>نصّ خارجيّ</p>
<div id="div1" style="border: solid blue 3px">
<p>نصّ div1</p>
<p>نصّ div1</p>
<p>نصّ div1</p>
<div id="div2" style="border: solid red 3px">
<p>نصّ div2</p>
<p>نصّ div2</p>
</div>
</div>
<p>نصّ خارجيّ</p>
<p>نصّ خارجيّ</p>
<button onclick="getAllParaElems();">
أظهر جميع عناصر p في المستند</button><br />
<button onclick="div1ParaElems();">
أظهر جميع عناصر p في المستند في العنصر div1</button><br />
<button onclick="div2ParaElems();">
أظهر جميع عناصر p في المستند في العنصر div2</button>
</body>
</html>
ملاحظات
عند استدعاء التّابع Document.getElementsByTagName() على مستند HTML، فستُحوَّل قيمة المعامل إلى أحرفٍ صغيرة (lower-case) قبل الاستمرار. هذا التصرّف غير مرغوب عند محاولة التّعامل مع عناصر SVG التي تكون حالة الأحرف فيها على شكل camelCase في شجرة فرعيّة داخل مستند HTML. ستجد التّابع Document.getElementsByTagNameNS() مُفيدًا في هذه الحالة.
التّابع Document.getElementsByTagName() مُشابهٌ للتّابع Element.getElementsByTagName() إلّا أنّ بحثه يشمل كامل المُستند عوضًا عن أولاد عنصرٍ واحد.