Document: createTreeWalker() method
Document
Document
The Document.createTreeWalker() creator method returns a newly created TreeWalker object.
Syntax
createTreeWalker(root)
createTreeWalker(root, whatToShow)
createTreeWalker(root, whatToShow, filter)
Parameters
root-
: A Node representing the root of the
TreeWalkerobject, which is the initial value of TreeWalker.currentNode. -
whatToShow -
: An
unsigned longrepresenting a bitmask created by combining the constant properties ofNodeFilter. It is a convenient way of filtering for certain types of node. It defaults to0xFFFFFFFF, representing theNodeFilter.SHOW_ALLconstant.Constant Numerical value Description NodeFilter.SHOW_ALL0xFFFFFFFFShows all nodes. NodeFilter.SHOW_ATTRIBUTE0x2Shows Attr nodes. NodeFilter.SHOW_CDATA_SECTION0x8Shows CDATASection nodes. NodeFilter.SHOW_COMMENT0x80Shows Comment nodes. NodeFilter.SHOW_DOCUMENT0x100Shows Document nodes. NodeFilter.SHOW_DOCUMENT_FRAGMENT0x400Shows DocumentFragment nodes. NodeFilter.SHOW_DOCUMENT_TYPE0x200Shows DocumentType nodes. NodeFilter.SHOW_ELEMENT0x1Shows Element nodes. NodeFilter.SHOW_ENTITY0x20Legacy, no longer effective. NodeFilter.SHOW_ENTITY_REFERENCE0x10Legacy, no longer effective. NodeFilter.SHOW_NOTATION0x800Legacy, no longer effective. NodeFilter.SHOW_PROCESSING_INSTRUCTION0x40Shows ProcessingInstruction nodes. NodeFilter.SHOW_TEXT0x4Shows Text nodes. [!NOTE] The
NodeFilter.SHOW_ATTRIBUTEconstant is only effective when the root is an attribute node. Since the parent of anyAttrnode is alwaysnull, TreeWalker.nextNode() and TreeWalker.previousNode() will never return anAttrnode. To traverseAttrnodes, use Element.attributes instead. -
filter - : A callback function or an object with an
acceptNode()method, which returnsNodeFilter.FILTER_ACCEPT,NodeFilter.FILTER_REJECT, orNodeFilter.FILTER_SKIP. The function or method will be called for each node in the subtree based atrootwhich is accepted as included by thewhatToShowflag to determine whether or not to include it in the list of iterable nodes:- If the return value is
NodeFilter.FILTER_ACCEPT, this node is included. - If the return value is
NodeFilter.FILTER_REJECT, any node in the subtree based at this node is not included. - If the return value is
NodeFilter.FILTER_SKIP, this node is not included.
- If the return value is
Return value
A new TreeWalker object.
Examples
Using whatToShow
This example uses whatToShow to transform text contents into upper case. Note that the text nodes of the descendants of the #root element are also traversed despite the fact that they are not child nodes of the #root element.
HTML
<div id="root">
This is a text node.
<span>And this is a <code>span</code> element.</span>
</div>
CSS
span {
background-color: aqua;
}
JavaScript
const treeWalker = document.createTreeWalker(
document.querySelector("#root"),
NodeFilter.SHOW_TEXT,
);
while (treeWalker.nextNode()) {
const node = treeWalker.currentNode;
node.data = node.data.toUpperCase();
}
Result
100%
Using filter
This example uses filter to escape text contents. For any text node, its content will be escaped using encodeURI() if it is a descendant of an .escape element but not of any .no-escape element.
HTML
<div>
<div>
This is not escaped. <span class="escape">But this is escaped.</span>
</div>
<div class="escape">This is escaped.</div>
<div class="no-escape">This is not escaped.</div>
</div>
<hr />
<div class="escape">
<div>
This is escaped. <span class="no-escape">But this is not escaped.</span>
</div>
<div class="no-escape">This is not escaped.</div>
</div>
<hr />
<div class="no-escape">
<div>This is not escaped.</div>
<div class="escape">This is not escaped.</div>
</div>
CSS
```css hidden div { margin: 0.25em 0; padding: 0.25em; } span { display: inline-block; }
```css
.escape {
border: dashed;
}
.no-escape {
border: solid;
}
JavaScript
const treeWalker = document.createTreeWalker(
document.body,
NodeFilter.SHOW_ELEMENT,
(node) =>
node.classList.contains("no-escape")
? NodeFilter.FILTER_REJECT
: node.closest(".escape")
? NodeFilter.FILTER_ACCEPT
: NodeFilter.FILTER_SKIP,
);
while (treeWalker.nextNode()) {
for (const node of treeWalker.currentNode.childNodes) {
if (node.nodeType === Node.TEXT_NODE && /\S/.test(node.data)) {
// Exclude whitespace-only text nodes
node.data = encodeURI(node.data.replace(/\s+/g, " "));
}
}
}
Result
100%
Specifications
Browser compatibility
See also
- TreeWalker: Related interface