`Document.getElementsByClassName()‎`

يُعيد التّابع Document.getElementsByClassName()‎ كائنًا مُشابهًا للمصفوفات يحتوي على جميع العناصر الأولاد التي تحمل نفس اسم الصّنف (class name) المُعطى. عند استدعائه على كائن المُستند، فسيُبحَثُ في كامل المُستند، ما يشمل العقدة الجذر. يُمكن كذلك استدعاء التّابع getElementsByClassName()‎ على أي عنصر؛ وسيُعيد العناصر الأولاد للعنصر الجذر المُحدَّد ذات أسماء الأصناف المعطاة.

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

var elements = document.getElementsByClassName(names);
// أو
var elements = rootElement.getElementsByClassName(names);

`elements‎`

كائنٌ حيّ من النّوع HTMLCollection‎ الذي يُمثّل مجموعة العناصِر التي وُجدت.

`names‎`

سلسلةٌ نصيّةٌ تُمثّل قائمة أسماء الأصناف المرغوب البحث عنها مفصولة بمساحة بيضاء (whitespace).

`getElementsByClassName‎`

يُمكن استدعاء هذا التّابع على أي عنصرٍ، ليس فقط على المُستند. وسيُستخدم العنصر الذي استدعيَ عليه بمثابة جذر البحث (أي نقطة بدايته).

أمثلة

الحصول على جميع العناصر ذات الصّنف 'test':

document.getElementsByClassName('test');

الحصول على جميع العناصر ذات الصّنف 'test' والصّنف 'red' في نفس الوقت:

document.getElementsByClassName('red test');

الحصول على جميع العناصر ذات الصّنف 'test' الموجودة داخل العنصر ذو المعرِّف'main' :

document.getElementById('main').getElementsByClassName('test');

يُمكننا كذلك استخدام توابع Array.prototype‎ على أي كائن HTMLCollection‎ عبر تمريره إلى قيمة الكائن this الخاصّ بالتّابع. في المثال التّالي، نجد جميع العناصِر div‎ ذات الصّنف 'test':

var testElements = document.getElementsByClassName('test');
var testDivs = Array.prototype.filter.call(testElements, function(testElement){
    return testElement.nodeName === 'DIV';
});

الوصول إلى العنصر الأول عبر اللاحقة [0]:

<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Document</title>
</head>
<body>
  <div id="parent-id">
    <p>hello word1</p>
    <p class="test">hello word2</p>
    <p>hello word3</p>
    <p>hello word4</p>
  </div>
  <script>
    var parentDOM = document.getElementById("parent-id");

    var test=parentDOM.getElementsByClassName("test");// هنا، لم نصل إلى العنصر الهدف بعد
    console.log(test);//HTMLCollection[1]

    var testTarget=parentDOM.getElementsByClassName("test")[0];// هنا نصل إلى العنصر
    console.log(testTarget);//<p class="test">hello word2</p>
  </script>
</body>
</html>

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	3	9	نعم	نعم

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

مواصفة W3C:‏ getElementsByClassName.