Javascript [Electronic resources] : The Definitive Guide (4th Edition) نسخه متنی

Availability

DOM Level 2 Traversal

Properties

Node

currentNode

The
current position of this TreeWalker and the node relative to which
all of the TreeWalker traversal methods operate. This is the node
most recently returned by one of those traversal methods or, if none
of those methods have been called yet, it is the same as the
root property.

Note that this is a read/write property, and you can set it to any
valid Document node -- even one that is not a descendant of the
original root node or one that would be rejected
by the filters used by this TreeWalker. If you change the value of
this property, the traversal methods operate relative to the new node
you specify. Attempting to set this property to
null throws a DOMException with a
code of NOT_SUPPORTED_ERR.

readonly boolean expandEntityReferences

This read-only property specifies
whether this TreeWalker object expands entity references it
encounters while traversing XML documents. The value of this property
is set by the call to Document.createTreeWalker(
).

readonly

NodeFilter

filter

The node
filter function, if any, that was specified for this TreeWalker in
the call to Document.createTreeWalker( ). If no
node filter is in use, this property is null.

readonly

Node

root

This read-only
property specifies the root node at which the
TreeWalker begins traversal. It is the initial value of the
currentNode property and is specified in the call
to Document.createTreeWalker( ).

readonly unsigned long whatToShow

This
read-only property is a set of bit flags (see
NodeFilter for a list of valid flags) that specifies
the types of Document nodes this TreeWalker will consider. If a bit
is not set in this property, the corresponding node type will always
be ignored by this TreeWalker. Note that the value of this property
is specified in the call to Document.createTreeWalker(
).

Methods

firstChild( )

Returns the first child of the current node that is not filtered out,
or null.

lastChild( )

Returns the last child of the current node that is not filtered out,
or null.

nextNode( )

Returns the next node (in document source order) that is not filtered
out, or null.

nextSibling( )

Returns the next sibling of the current node that is not filtered
out, or null.

parentNode( )

Returns the parent or nearest ancestor of the current node that is
not filtered out, or null.

previousNode( )

Returns the previous node (in document source order) that is not
filtered out, or null.

previousSibling( )

Returns the nearest previous sibling of the current node that is not
filtered out, or null.

Description

A TreeWalker filters a specified document subtree and defines methods
that allow programs to traverse the filtered tree (which may have a
significantly different structure than the original document tree).
Create a TreeWalker object with the createTreeWalker(
) method of the Document object. Once a TreeWalker is
created, you can use its firstChild( ) and
nextSibling( ) methods to traverse the filtered
subtree it represents in the same way that you might use the
firstChild and nextSibling
properties of the Node interface to traverse an unfiltered document
tree.

A TreeWalker applies the same two filtration steps that a
NodeIterator does. The various traversal methods defined by
TreeWalker will return only nodes that pass both filters. First, the
node type must be one of the types specified by the
whatToShow property. See NodeFilter
for a list of constants that can be combined to specify the
whatToShow argument to
Document.createTreeWalker( ). Second, if the
filter property is not null,
each node that passes the whatToShow test is
passed to the filter function specified by the
filter property. If this function returns
NodeFilter.FILTER_ACCEPT, the node is returned. If
it returns NodeFilter.FILTER_REJECT, the node and
all of its descendants are skipped by the TreeWalker (this differs
from NodeIterator filtration, in which descendants are never
automatically rejected). If the node filter function returns
NodeFilter.FILTER_SKIP, the TreeWalker ignores the
node but does consider its descendants.

Unlike NodeIterators, TreeWalkers are not modified when the
underlying document is modified. The current node of a TreeWalker
remains unchanged, even if that node is removed from the document.
(And, in this case, the TreeWalker can be used to traverse the tree
of deleted nodes, if any, that surround that current node.)

Example

// A NodeFilter that rejects <font> tags and any element with a
// class="sidebar" attribute and any descendants of such an element
var filter = function(n) {
if (n.nodeName == "FONT") return NodeFilter.FILTER_SKIP;
if (n.nodeType == Node.ELEMENT_NODE && n.className == "sidebar")
return NodeFilter.FILTER_REJECT;
return NodeFilter.FILTER_ACCEPT;
}
// Create a TreeWalker using the filter above
var tw = document.createTreeWalker(document.body,
  // Walk HTML document body
// Consider all nodes except comments
~NodeFilter.SHOW_COMMENT,
filter,  // Use filter above
false);  // Don't expand entity references
// Here's a recursive function that traverses a document using a TreeWalker
function traverse(tw) {
// Remember the current node
var currentNode = tw.currentNode;
// Loop through the children of the current node of the TreeWalker
for(var c = tw.firstChild(  ); c != null; c = tw.nextSibling(  )) {
process(c);    // Do something to process the child
traverse(tw);  // And recursively process its children
}
// Put the TreeWalker back in the state we found it in
tw.currentNode = currentNode;
}

See Also

NodeFilter, NodeIterator; Chapter 17

Returned by

Document.createTreeWalker( )