Document:createTreeWalker() 方法

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

创建器方法 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

参见