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 对象。

语法

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 节点的父节点恒为 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，则不包含此节点。

HTML

html

<div id="root">
  此节点为 Text 节点。<span>而此节点为 <code>span</code> 元素。</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>此文本未被转义。<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

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

结果

规范

Specification
DOM Standard # dom-document-createtreewalker

浏览器兼容性

BCD tables only load in the browser

参见

TreeWalker——相关接口