الفرق بين المراجعتين لصفحة: «JavaScript/Document/querySelector»
إضافة الصّفحة |
طلا ملخص تعديل |
||
| سطر 2: | سطر 2: | ||
يُعيد التّابع <code>Document.querySelector()</code> أول كائنٍ من النّوع <code>[[JavaScript/Element|Element]]</code> الذي يُمثّل العنصر المُوافِق للمُحدِّد أو المحدّدات المعطاة. ويُعيد القيمة <code>null</code> في حالة لم يجِد أيّ عنصر. | يُعيد التّابع <code>Document.querySelector()</code> أول كائنٍ من النّوع <code>[[JavaScript/Element|Element]]</code> الذي يُمثّل العنصر المُوافِق للمُحدِّد أو المحدّدات المعطاة. ويُعيد القيمة <code>null</code> في حالة لم يجِد أيّ عنصر. | ||
مُلاحظة: يتمّ البحث باستعمال المرور على العمق أولا قبل التّرتيب (depth-first pre-order traversal) حول عقد المستند بدايةً من أول عنصر في هيكل المستند ويُكرّر (iterating) حول العقد في القائمة مرتّبةً حسب عدد العقد الأبناء. | '''مُلاحظة:''' يتمّ البحث باستعمال المرور على العمق أولا قبل التّرتيب (depth-first pre-order traversal) حول عقد المستند بدايةً من أول عنصر في هيكل المستند ويُكرّر (iterating) حول العقد في القائمة مرتّبةً حسب عدد العقد الأبناء. | ||
==البنية العامة== | ==البنية العامة== | ||
| سطر 31: | سطر 31: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===محدد أكثر | ===محدد أكثر تعقيدًا=== | ||
يُمكن للمحدّدات أن تكون طريقةً فعّالة جدًّا للحصول على عناصِر توافق شروطا معقّدة كما في المثال التّالي. | يُمكن للمحدّدات أن تكون طريقةً فعّالة جدًّا للحصول على عناصِر توافق شروطا معقّدة كما في المثال التّالي. | ||
في هذا المثال، سيُعاد أول عنصر <code><input></code> في المستند ذو الاسم "login" (أي <code><input name="login"/></code>) الموجود داخل العنصر <code><nowiki><div></nowiki></code> ذو الصّنف <code>"user-panel main"</code> (أي <code><nowiki><div class="user-panel main"></nowiki></code>): | في هذا المثال، سيُعاد أول عنصر <code>[[HTML/input|<input>]]</code> في المستند ذو الاسم "login" (أي <code><input name="login"/></code>) الموجود داخل العنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> ذو الصّنف <code>"user-panel main"</code> (أي <code><nowiki><div class="user-panel main"></nowiki></code>): | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
var el = document.querySelector("div.user-panel.main input[name='login']"); | var el = document.querySelector("div.user-panel.main input[name='login']"); | ||
مراجعة 15:41، 28 مارس 2018
يُعيد التّابع 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