文档：createTreeWalker() 方法

Baseline 已广泛支持

此特性已相当成熟，可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来，各浏览器均已提供此特性。

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

语法

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

参数

根

一个 Node，代表 TreeWalker 对象的根，它是 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 节点的父节点始终是 null，TreeWalker.nextNode() 和 TreeWalker.previousNode() 将永远不会返回 Attr 节点。要遍历 Attr 节点，请改用 Element.attributes。

filter 可选

一个回调函数或一个带有 acceptNode() 方法的对象，它返回 NodeFilter.FILTER_ACCEPT、NodeFilter.FILTER_REJECT 或 NodeFilter.FILTER_SKIP。该函数或方法将针对 root 处的子树中的每个节点调用，这些节点被 whatToShow 标志接受为包含在内，以确定是否将其包含在可迭代节点列表中。

如果返回值为 NodeFilter.FILTER_ACCEPT，则包含此节点。
如果返回值为 NodeFilter.FILTER_REJECT，则不包含此节点处子树中的任何节点。
如果返回值为 NodeFilter.FILTER_SKIP，则不包含此节点。

返回值

一个新的 TreeWalker 对象。

示例

使用 whatToShow

此示例使用 whatToShow 将文本内容转换为大写。请注意，即使 #root 元素的后代文本节点不是 #root 元素的子节点，它们也会被遍历。

HTML

html

<div id="root">
  This is a text node.
  <span>And this is a <code>span</code> element.</span>
</div>

CSS

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();
}

结果

使用 filter

此示例使用 filter 转义文本内容。对于任何文本节点，如果它是 .escape 元素的后代但不是任何 .no-escape 元素的后代，则其内容将使用 encodeURI() 进行转义。

HTML

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

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, " "));
    }
  }
}

结果

规范

规范
DOM # dom-document-createtreewalker

浏览器兼容性

另见

TreeWalker：相关接口

帮助改进 MDN

了解如何贡献

此页面最后由 MDN 贡献者于 2025 年 6 月 23 日修改。

在 GitHub 上查看此页面 • 报告此内容的问题