Document:createTreeWalker() 方法

创建器方法 Document.createTreeWalker() 返回新创建的 TreeWalker 对象。

语法

js
createTreeWalker(root)
createTreeWalker(root, whatToShow)
createTreeWalker(root, whatToShow, filter)

参数

root

表示 TreeWalker 对象的根节点的 Node,为 TreeWalker.currentNode 的初始值。

whatToShow 可选

表示位掩码的 unsigned long,由 NodeFilter 的常属性组合而成。此参数便于筛选出特定类型的节点。其默认值为 0xFFFFFFFF,表示 NodeFilter.SHOW_ALL 常数。

常数 数值 描述
NodeFilter.SHOW_ALL 0xFFFFFFFF 显示所有节点。
NodeFilter.SHOW_ATTRIBUTE 0x2 显示 Attr 节点。
NodeFilter.SHOW_CDATA_SECTION 0x8 显示 CDATASection 节点。
NodeFilter.SHOW_COMMENT 0x80 显示 Comment 节点。
NodeFilter.SHOW_DOCUMENT 0x100 显示 Document 节点。
NodeFilter.SHOW_DOCUMENT_FRAGMENT 0x400 显示 DocumentFragment 节点。
NodeFilter.SHOW_DOCUMENT_TYPE 0x200 显示 DocumentType 节点。
NodeFilter.SHOW_ELEMENT 0x1 显示 Element 节点。
NodeFilter.SHOW_ENTITY 已弃用 0x20 旧式参数,不再有效。
NodeFilter.SHOW_ENTITY_REFERENCE 已弃用 0x10 旧式参数,不再有效。
NodeFilter.SHOW_NOTATION 已弃用 0x800 旧式参数,不再有效。
NodeFilter.SHOW_PROCESSING_INSTRUCTION 0x40 显示 ProcessingInstruction 节点。
NodeFilter.SHOW_TEXT 0x4 显示 Text 节点。

备注: 由于任意 Attr 节点的父节点恒为 nullTreeWalker.nextNode()TreeWalker.previousNode() 永远不会返回 Attr 节点。遍历 Attr 节点请使用 Element.attributes

filter 可选

回调函数或含 acceptNode() 方法的对象,其返回值为 NodeFilter.FILTER_ACCEPTNodeFilter.FILTER_REJECTNodeFilter.FILTER_SKIP。对于以 root 为根节点的子树中被 whatToShow 标志所接受的任意节点,将调用此函数或方法决定是否在迭代节点列表中包含此节点:

  • 若返回值为 NodeFilter.FILTER_ACCEPT,则包含此节点。
  • 若返回值为 NodeFilter.FILTER_REJECT,则不包含以此节点为根的子树中的任意节点。
  • 若返回值为 NodeFilter.FILTER_SKIP,则不包含此节点。

返回值

新的 TreeWalker 对象。

示例

使用 whatToShow

此示例使用 whatToShow 将文本内容转换为大写。注意到 #root 后代的文本节点虽然并非 #root 元素的子节点,但也将被遍历。

HTML

html
<div id="root">
  此节点为 Text 节点。<span>而此节点为 <code>span</code> 元素。</span>
</div>

CSS

css
span {
  background-color: aqua;
}

JavaScript

js
const treeWalker = document.createTreeWalker(
  document.querySelector("#root"),
  NodeFilter.SHOW_TEXT,
);

while (treeWalker.nextNode()) {
  const node = treeWalker.currentNode;
  node.data = node.data.toUpperCase();
}

结果

使用 filter

此示例使用 filter 将文本内容转义。对于任意文本节点,若其为某个 .escape 元素的后代且非任何 .no-escape 元素的后代,则用 encodeURI() 将其转义。

HTML

html
<div>
  <div>此文本未被转义。<span class="escape">但此文本被转义。</span></div>
  <div class="escape">此文本被转义。</div>
  <div class="no-escape">此文本未被转义。</div>
</div>
<hr />
<div class="escape">
  <div>此文本被转义。<span class="no-escape">但此文本未被转义。</span></div>
  <div class="no-escape">此文本未被转义。</div>
</div>
<hr />
<div class="no-escape">
  <div>此文本未被转义。</div>
  <div class="escape">此文本未被转义。</div>
</div>

CSS

css
.escape {
  border: dashed;
}
.no-escape {
  border: solid;
}

JavaScript

js
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)) {
      // 排除仅含空白符的文本节点
      node.data = encodeURI(node.data.replace(/\s+/g, " "));
    }
  }
}

结果

规范

Specification
DOM Standard
# dom-document-createtreewalker

浏览器兼容性

BCD tables only load in the browser

参见