Document.evaluate()
يُنشئ التّابع Document.evaluate() كائنًا من النّوع XPathResult مبني على تعبير XPath ومعاملات معطاة أخرى.
البنية العامة
var xpathResult = document.evaluate(
xpathExpression,
contextNode,
namespaceResolver,
resultType,
result
);
المعاملات
xpathExpression
سلسة نصيّة تُمثّل تعبير XPath المرغوب تقديره (evaluate).
contextNode
يُحدّد عقدة السّياق للاستعلام (انظر مواصفة XPath). من الشّائع تمرير كائن المستند document كعقدة سياق.
namespaceResolver
دالّة تُمرَّر لها سابقات مجالات الأسماء (namespace prefixes) لتُعيد سلسلةً نصيّة تُمثّل عنوان URI مجال الأسماء المرتبط بالسّابقة المُمرَّرة. ستُستعمل لحلّ السّابقات داخل تعبير XPath نفسه، ليُمكِنَ موافقتُها مع المستند. القيمة null شائعة لمستندات HTML أو عند عدم استخدام أية سابقات مجالات أسماء.
resultType
عدد صحيح يُمثّل نوع نتيجة XPathResult المرغوب إعادتها. استعمل خاصيّات الثوابت المسمّاة، مثل XPathResult.ANY_TYPE التّابعة للدالة البانيّة الخاصّة بالكائن XPathResult، والتي تُمثّل الأعداد الصّحيحة من 0 إلى 9.
result
كائنٌ موجود مسبقا من النّوع XPathResult لاستعماله من أجل النّتائج. القيمة null أكثر قيمةٍ شائعةٍ وستنشئ كائنًا جديدًا من النّوع XPathResult.
مثال
var headings = document.evaluate("/html/body//h2", document, null, XPathResult.ANY_TYPE, null);
/* البحث في المستند عن جميع عناصر
* h2
* ستكون النّتيجة في الغالب مكرّر عقد غير مرتّب */
var thisHeading = headings.iterateNext();
var alertText = "تروسيات المستوى الثّاني في هذا المستند هي \n";
while (thisHeading) {
alertText += thisHeading.textContent + "\n";
thisHeading = headings.iterateNext();
}
alert(alertText); // ينبّه بنصوص جميع عناصر تروسيات المستوى الثّاني
ملاحظة: في المثال أعلاه، من المفضّل استعمال تعبير XPath أكثر تفصيلًا من الاختصارات الشّائعة مثل //h2. وذلك لأنّ محدّدات XPath المُفصّلة كما في المثال أعلاه تمنح أداءً أفضل بكثير، خاصّة إن كان المستند كبيرًا. هذا لأنّ تقدير الاستعلامات لا يضيّع وقتًا في زيارة عقد زيادةً عن الحاجة. استخدام // بطيء عامّةً لأنّه يزور جميع العقد من الجذر وجميع العقد الفرعيّة بحثًا عن موافَقات مُمكنة.
يُمكن الحصول على تحسين أداء أكثر عبر استخدام معامل السيّاق بعناية. على سبيل المثال، إن كنت تعلم بأنّ المحتوى الذي تبحث عنه موجود في مكان ما داخل وسم body، فتستطيع استعمال ما يلي:
document.evaluate(".//h2", document.body, null, XPathResult.ANY_TYPE, null);
لاحظ أنّنا استخدمنا أعلاه الخاصيّة document.body عوضًا عن الكائن document مباشرةً وذلك لكي يبدأ XPath بالبحث انطلاقًا من عنصر جسم المستند body. في هذا المثال، النّقطة "." مهمّة لأنّها تُشير إلى أنّ الاستعلام يجب أن يبدأ من عقدة السّياق document.body، وإن لم نضع هذه النّقطة (أي استعمال //h2 فقط) فسيبدأ الاستعلام من العقدة الجذر (html)، ما سيكون إسرافًا في هذه الحالة.
انظر مقدّمة إلى استخدام XPath في JavaScript للاستزادة.
ملاحظات
- يُمكن تقدير تعابير XPath على كلّ من مستندات HTML ومستندات XML.
- يجب استخدام التّابع
evaluateعلى كائن المستند المرغوب تقديره إن لم يكن ذلك المستند الحالي، أي مثلًا لاستعمال التّابع على مستند XML، فقد تحتاج إلى استعمال التّابعsomeXMLDoc.evaluate()، مع كونsomeXMLDocكائن مستند XML.
أنواع النتائج
هذه هي القيم المدعومة للمعامل resultType الخاصّ بالتّابع evaluate:
| نوع النّتيجة | القيمة | الوصف |
|---|---|---|
ANY_TYPE
|
0
|
أي نوعٍ يُنتَج من طرف التّعبير طبيعيًّا كيفما كان. |
NUMBER_TYPE
|
1
|
مجموعة نتائج تحتوي على عدد واحد فقط. مُفيدة في تعبير XPath يستعمل الدّالة count() مثلًا.
|
STRING_TYPE
|
2
|
مجموعة نتائج تحتوي على سلسلة نصيّة واحدة. |
BOOLEAN_TYPE
|
3
|
مجموعة نتائج تحتوي على قيمة منطقيّة واحدة. مفيدة في تعبير XPath يستخدم الدّالة not() مثلًا.
|
UNORDERED_NODE_ITERATOR_TYPE
|
4
|
مجموعة نتائج تحتوي على جميع العقد التي توافق التعبير. لا تكون العقد في مجموعة النّتائج مُرتّبةً كما تظهر في المستند بالضّرورة. |
ORDERED_NODE_ITERATOR_TYPE
|
5
|
مجموعة نتائج تحتوي على جميع العقد التي توافق التعبير. تكون العقد في مجموعة النّتائج مُرتّبةً كما تظهر في المستند. |
UNORDERED_NODE_SNAPSHOT_TYPE
|
6
|
مجموعة نتائج تحتوي على لقطات (snapshots) جميع العقد التي توافق التّعبير. لا تكون العقد في مجموعة النّتائج مُرتّبةً كما تظهر في المستند بالضّرورة. |
ORDERED_NODE_SNAPSHOT_TYPE
|
7
|
مجموعة نتائج تحتوي على لقطات جميع العقد التي توافق التّعبير. تكون العقد في مجموعة النّتائج مُرتّبةً كما تظهر في المستند. |
ANY_UNORDERED_NODE_TYPE
|
8
|
مجموعة نتائج تحتوي على أية عقدة وحيدة توافق التعبير. لا تكون العقدة أول عقدة توافق التّعبير في المستند بالضّرورة. |
FIRST_ORDERED_NODE_TYPE
|
9
|
مجموعة نتائج تحتوي على أول عقدة توافق التعبير في المستند. |
النتائج من أنواع NODE_ITERATOR تحتوي على مراجع تشير إلى العقد في المستند. تعديل عقدة سيُعطّل المُكرّر (iterator). وستفشل محاولة التّكرار (iterate) حول النّتائج بعد تعديل عقدةٍ معيّنة.
النتائج من أنواع NODE_SNAPSHOT هي لقطات، أي أنّها قوائم تحتوي على العقد التي توافق التّعبير. يُمكنك إجراء تعديلات على المستند عبر تعديل عقد اللقطات. تعديل المستند لا يُعطّل اللقطة، لكن، إن عُدِّل المستند، فاللقطات لا تتوافق مع الحالة الحاليّة للمستند، وذلك لأنّ العقد قد تنتقل إلى مكان آخر أو تتغيّر أو تُضاف أو تُحذف.
دعم المتصفحات
| الميزة | Chrome | Firefox | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| الدعم الأساسي | 1 | 1.5 | لا | 9 | نعم |
على النّقيض من متصفّح Internet Explorer، يدعم المتصفّح Edge هذا التّابع.