`Document.querySelectorAll()‎`

يُعيد التّابع Document.querySelectorAll()‎ كائنًا ثابتًا (غير حيّ) من النّوع NodeList الذي يُمثّل قائمة عناصر المستند التي تُوافق المُحدّدات المعطاة.

مُلاحظة: هذا التّابع مبني على التّابع ParentNode.querySelectorAll()‎.

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

elementList = parentNode.querySelectorAll(selectors);

`selectors‎`

سلسلة نصيّة من النّوع DOMString تحتوي على مُحدّد واحدٍ أو أكثر لمُوافقته مع عناصر المستند والبحث عن العنصر المرغوب. يجب على هذه السّلسلة النّصيّة أن تكون مُحدّد CSS صالح، إن لم يكن كذلك، فسيُرمى استثناء SyntaxError، انظر هذه الصّفحة للمزيد حول المُحدّدات وكيفيّة إدارتها. يُمكن تحديد عدّة محدّدات عبر فصلها بفاصلة (,).

مُلاحظة: يجب تهريب (escaping) المحارف التي ليست جزءًا من بنية CSS العامّة باستعمال محرف \. ولأنّ JavaScript تستعمل كذلك المحرف \ لتهريب المحارف، فيجب كتابة السلاسل النّصيّة الحرفيّة بعنايةٍ خاصّةٍ عند استعمال هذه المحارف. انظر فقرة تهريب المحارف الخاصّة في هذه الصّفحة.

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

كائنٌ غير حيّ من النّوع NodeList يحتوي كائنًا واحدًا من النّوع Element لكلّ عنصرٍ يوافق واحدًا على الأقل من المُحدّدات المُعطاة.

مُلاحظة: إن كانت المحدّدات selectors تشمل عنصر CSS زائف، فالقائمة المُعادة ستكون دائمًا فارغة.

الاستثناءات

`SyntaxError‎`

يُرمى في حالة كانت بنية المُحدّدات selectors‎ خطأ.

أمثلة

الحصول على قائمة عناصر موافقة

للحصول على كائن NodeList لجميع عناصر ‎<p>‎‎ في المستند:

var matches = document.querySelectorAll("p");

يُعيد المثال التّالي قائمة بجميع عناصر <div> داخل المستند ذات الصّنف "note" أو ذات الصّنف "alert":

var matches = document.querySelectorAll("div.note, div.alert");

هنا نحصل على قائمة العناصر ‎<p>‎‎ أولاد العنصر<div> المباشرين ذو الصّنف "highlighted"، والموجودة داخل عنصرٍ حاوٍ (container) مُعرّفه "test":

var container = document.querySelector("#test");
var matches = container.querySelectorAll("div.highlighted > p");

يستعمل المثال التّالي مُحدّد خاصيّات لإعادة قائمةٍ بعناصر iframe التي تحتوي خاصيّة تُسمّى "data-src" في المستند:

var matches = document.querySelectorAll("iframe[data-src]");

أمّا في هذا المثال، نستعمل مُحدّد الخاصيّات لإعادة قائمةٍ بعناصر القوائم <li> الموجودة داخل قائمةٍ ذات المُعرّف "userlist" ذات خاصيّة باسم "data-active" بقيمة "1" .

var container = document.querySelector("#userlist");
var matches = container.querySelectorAll("li[data-active=1]");

الوصول إلى العناصر الموافقة

بعد أن يُعاد الكائن NodeList الذي يحمل العناصر الموافقة، ستتمكّن من التّعامل معها كما تتعامل مع أية مصفوفة. إن كانت المصفوفة خاوية (أي أنّ الخاصيّة length تُساوي 0)، فهذا يعني بأنّه لم يوجد أي عنصر. إن لم يكن الأمر كذلك، فتستطيع الوصول إلى محتويات القائمة كما تصل إلى محتويات المصفوفة. ويمكنك استعمال أية حلقة تكرار معروفة، مثل:

var highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach(function(userItem) {
  deleteUser(userItem);
});

ملاحظات

يعمل التّابع querySelectorAll‎()‎ بشكلٍ مختلف عن معظم مكتبات JavaScript التي تُستعمل للتّعامل مع DOM، ما قد يؤدّي إلى نتائج غير متوقّعة.

لنضع كمثال مستند HTML ذو ثلاثة عناصر <div> متداخلة هكذا:

<div class="outer">
  <div class="select">
    <div class="inner">
    </div>
  </div>
</div>

في جزء JavaScript نضع:

var select = document.querySelector('.select');
var inner = select.querySelectorAll('.outer .inner');
inner.length; // هنا، القيمة هي واحد وليست صفرا

في المثال أعلاه، عند تحديد "‎.‎outer ‎.‎inner" في سياق <div> ذو الصنف "select"، فالعنصر ذو الصنف "‎.‎inner" يوجد رغم أنّ "‎.‎outer" ليس من أولاد العنصر الرّئيسيّ الذي أُجرِيَ عليه البحث ( أي "‎.‎select"). افتراضيًّا يتحقّق التّابع querySelectorAll‎()‎ فقط ممّا إذا كان آخر عنصر من المُحدّد موجودًا داخل نطاق البحث.

يسترجع الصنف الزّائف ‎:‎scope التّصرّف المُتوقّع، إذ لا يوافق سوى المحدّدات على أولاد العنصر الرّئيسيّ:

var select = document.querySelector('.select');
var inner = select.querySelectorAll(':scope .outer .inner');
inner.length; // 0

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	1	3.5	8	10	3.2
الصنف الزّائف `‎:‎scope`	نعم	32	لا	15	7

انظر أيضًا

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

مواصفة DOM.
مواصفة Selectors API Level 2.
مواصفة DOM4.
مواصفة Selectors API Level 1.