`Document.querySelector()‎`

يُعيد التّابع Document.querySelector()‎ أول كائنٍ من النّوع Element الذي يُمثّل العنصر المُوافِق للمُحدِّد أو المحدّدات المعطاة. ويُعيد القيمة null في حالة لم يجِد أيّ عنصر.

مُلاحظة: يتمّ البحث باستعمال المرور على العمق أولًا قبل التّرتيب (depth-first pre-order traversal) حول عقد المستند بدايةً من أول عنصر في هيكل المستند ويُكرّر (iterating) حول العقد في القائمة مرتّبةً حسب عدد العقد الأبناء.

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

element = document.querySelector(selectors);

`selectors‎`

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

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

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

كائنٌ من النّوع Element يُمثّل أول عنصر يوافق مُحدّدات CSS المُعطاة.

إن أردت قائمةً بجميع العناصِر المُوافقة للمحدّدات المعطاة، فعليك استعمال التّابع Document.querySelectorAll()‎ عوضًا عن هذا التّابع.

الاستثناءات

`SYNTAX_ERR‎`

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

أمثلة

إيجاد أول عنصر يوافق صنفه الصنف المعطى

في المثال التّالي، سنبحث عن أول عنصرٍ ذي الصّنف ‎"‎myclass‎"‎‎ في المستند:

var el = document.querySelector(".myclass");

محدد أكثر تعقيدًا

يُمكن للمحدّدات أن تكون طريقةً فعّالة جدًّا للحصول على عناصِر توافق شروطًا معقّدة كما في المثال التّالي.

في هذا المثال، سيُعاد أول عنصر <input> في المستند ذو الاسم ‎‎"‎‎login‎‎"‎‎‎ (أي ‎<input ‎name‎=‎"‎login‎"‎‎‎‎>‎) الموجود داخل العنصر <div> ذو الصّنف "user-panel main" (أي <‎div ‎class‎=‎"‎user-panel main‎"‎>):

var el = document.querySelector("div.user-panel.main input[name='login']");

ملاحظات

إن كان المحدّد selector يوافق معرّفًا (ID) استُخدِم أكثر من مرّة واحدة في المستند خطأً، فالعنصر الأول ذو المعرّف المُعطى هو الذي يُعاد.

لن تُعيد عناصر CSS الزائفة أية عناصر، وذلك حسب ما حُدّد في مواصفة واجهة المُحدّدات البرمجيّة.

تهريب المحارف الخاصّة

لمُوافقة مُعرّف أو مُحدّدات لا تتّبع بنية CSS العامّة المعياريّة (عبر استخدام علامة : أو فراغ خطأً مثلًا)، فعليك تهريب المحرف باستخدام علامة "\"‎. ولأنّ هذه العلامة تُستعمل كمحرف تهريب في JavaScript كذلك، فعليك تهريب المحرف مرّتين إن كنت تُريد استخدام سلسلة نصيّة حرفيّة (literal string)، مرّةً للسلسلة النّصيّة الخاصّة بلغة JavaScript ومرّةً أخرى للتّابع Document.querySelector()‎:

<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
  // هنا 
  // \b
  // محرف تحكم
  // backspace control character
  console.log('#foo\bar');               // "#fooar" (\b is the backspace control character)
  document.querySelector('#foo\bar');    // لا توافق أي عنصر

  console.log('#foo\\bar');              // "#foo\bar"
  console.log('#foo\\\\bar');            // "#foo\\bar"
  document.querySelector('#foo\\\\bar'); // توافق العنصر الأول

  document.querySelector('#foo:bar');    // لا توافق أي عنصر
  document.querySelector('#foo\\:bar');  //  توافق العنصر الثّاني
</script>

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	1	3.5	8	10	3.2

انظر أيضًا

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

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