文件：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 上檢視此頁面 • 報告此內容的問題