عرض مصدر JavaScript/Document/createTreeWalker

<noinclude>{{DISPLAYTITLE:<code>Document.createTreeWalker()‎</code>}}</noinclude>

يُنشئ التّابع <code>Document.createTreeWalker()‎</code> كائنًا جديدًا من النّوع <code>[[JavaScript/TreeWalker|TreeWalker]]</code> ويُعيده.

==البنية العامة==
<syntaxhighlight lang="javascript">
treeWalker = document.createTreeWalker(root, whatToShow, filter, entityReferenceExpansion);
</syntaxhighlight>

===المعاملات===
====<code>root</code>====
العقدة <code>[[JavaScript/Node|Node]]</code> الجذر لمرور الكائن <code>[[JavaScript/TreeWalker|TreeWalker]]</code>. عادةً ما يكون عنصرًا مملوكًا من طرف المُستند.

====<code>whatToShow</code>====
قيمة اختياريّةٌ من النّوع  <code>unsigned long</code> تُمثّل قيمة bitmask تُنشأُ عبر دمج الخاصيّات الثّابتة الخاصّة بالكائن <code>[http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter NodeFilter]</code>. وهي طريقة جيّدة لترشيح بعض أنواع العقد. القيمة الافتراضيّة هي <code>0xFFFFFFFF</code> وتُمثّل الثّابتة <code>SHOW_ALL</code>.

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

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

==== <code>entityReferenceExpansion</code> ====
قيمةٌ منطقيّة من النّوع <code>[[JavaScript/Boolean|Boolean]]</code>؛ ;وهو '''مُعاملٌ محذوف''' لا يجب استخدامه.

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

<syntaxhighlight lang="javascript">
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);
</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Internet Explorer
!Firefox
!Opera
!Safari
|-
! الدعم الأساسي
|1
|9
|2
|9
|3
|-
! <code>whatToShow</code> و<code>filter</code> مُعاملات اختياريّة
|1
|لا
|12
|9
|3
|-
|}

==مصادر ومواصفات==
* مواصفة [https://dom.spec.whatwg.org/#dom-document-createtreewalker DOM] حذفت هذه المواصفة المُعامل <code>entityReferenceExpansion</code> وجعلت من كلّ من <code>whatToShow</code> و<code>filter</code> مُعاملاتٍ اختياريّة.
* مواصفة [https://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#NodeIteratorFactory-createTreeWalker Document Object Model (DOM) Level 2 Traversal and Range Specification]

 [[تصنيف:JavaScript]]
 [[تصنيف:Web API]]
 [[تصنيف:DOM]]
 [[تصنيف:Document]]