Document.createTreeWalker()‎

يُنشئ التّابع Document.createTreeWalker()‎ كائنًا جديدًا من النّوع TreeWalker ويُعيده.

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

treeWalker = document.createTreeWalker(root, whatToShow, filter, entityReferenceExpansion);

المعاملات

root

العقدة Node الجذر لمرور الكائن TreeWalker. عادةً ما يكون عنصرًا مملوكًا من طرف المُستند.

whatToShow

قيمة اختياريّةٌ من النّوع unsigned long تُمثّل قيمة bitmask تُنشأُ عبر دمج الخاصيّات الثّابتة الخاصّة بالكائن NodeFilter. وهي طريقة جيّدة لترشيح بعض أنواع العقد. القيمة الافتراضيّة هي 0xFFFFFFFF وتُمثّل الثّابتة SHOW_ALL.

الثّابتة	القيمة الرّقميّة	الوصف
NodeFilter.SHOW_ALL	‎-1 (وهي القيمة القصوى للنّوع unsigned long)	اعرض جميع العقد.
NodeFilter.SHOW_ATTRIBUTE	2	قيمةٌ مُهملَة تعرض عقد الخصائص من النّوع Attr.
NodeFilter.SHOW_CDATA_SECTION	8	قيمةٌ مُهملَة تعرض العقد من النّوع CDATASection.
NodeFilter.SHOW_COMMENT	128	تعرض العقد من النّوع Comment.
NodeFilter.SHOW_DOCUMENT	256	تعرض العقد من النّوع Document.
NodeFilter.SHOW_DOCUMENT_FRAGMENT	1024	تعرض العقد من النّوع DocumentFragment.
NodeFilter.SHOW_DOCUMENT_TYPE	512	تعرض العقد من النّوع DocumentType.
NodeFilter.SHOW_ELEMENT	1	تعرض العقد من النّوع Element.
NodeFilter.SHOW_ENTITY	32	قيمةٌ مُهملَة تعرض العقد من النّوع Entity.
NodeFilter.SHOW_ENTITY_REFERENCE	16	قيمةٌ مُهملَة تعرض العقد من النّوع EntityReference.
NodeFilter.SHOW_NOTATION	2048	قيمةٌ مُهملَة تعرض العقد من النّوع Notation.
NodeFilter.SHOW_PROCESSING_INSTRUCTION	64	تعرض العقد من النّوع ProcessingInstruction.
NodeFilter.SHOW_TEXT	4	تعرض العقد من النّوع Text.

filter

مُعاملٌ اختياريّ يُمثّل كائنًا يُطبِّق الواجهة NodeFilter؛ يُستدعى التّابع acceptNode()‎ الخاصّ بهذه الواجهة لتحديد ما إذا كانت العقدة ستُقبل أو لا حسب ما حُدِّد من طرف المُعامل whatToShow‎.

entityReferenceExpansion

قيمةٌ منطقيّة من النّوع Boolean؛ ;وهو مُعاملٌ محذوف لا يجب استخدامه.

أمثلة

يمرّ المثال التّالي عبر جميع العقد في جسد المُستند، ثمّ تختزل (reduce) مجموعة العقد إلى عناصر، وتقوم بالمرور على كلّ عقدة حسب ما إذا كانت مقبولة أو لا (يُمكن اختزال المجموعة في التّابع acceptNode()‎ عوضًا عن ذلك)، بعدها يُستخدم المُكرِّرُ (iterator) التّابع للكائن TreeWalker الذي أُنشئ للمرور عبر العقد (والتي أصبحت عناصر الآن) ثمّ يُضيفها إلى آخر المصفوفة.

var treeWalker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  { acceptNode: function(node) { return NodeFilter.FILTER_ACCEPT; } },
  false
);

var nodeList = [];

while(treeWalker.nextNode()) nodeList.push(treeWalker.currentNode);

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

الميزة	Chrome	Internet Explorer	Firefox	Opera	Safari
الدعم الأساسي	1	9	2	9	3
whatToShow وfilter مُعاملات اختياريّة	1	لا	12	9	3

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

• مواصفة DOM حذفت هذه المواصفة المُعامل entityReferenceExpansion وجعلت من كلّ من whatToShow وfilter مُعاملاتٍ اختياريّة.
• مواصفة Document Object Model (DOM) Level 2 Traversal and Range Specification