JavaScript TreeWalker.whatToShow 怎样区分节点类型掩码与自定义过滤器
来源:17golang原创
时间:2026-11-18 12:22:22 223浏览 收藏
如果你在用 TreeWalker 遍历 DOM,最容易混淆的是 whatToShow 和第三个参数 filter。前者只回答“哪些节点类型有资格被看到”,后者才回答“这个具体节点是否符合业务条件”。实用写法是先用 NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT 缩小类型范围,再在过滤器中处理类名、属性或文本内容。
两层条件不要互相替代:whatToShow 是创建遍历器时确定的只读位掩码,filter 是按候选节点调用的自定义规则。只要把这条边界记住,TreeWalker.whatToShow 返回的数字就不再是难以解释的“魔法值”。
先分清 whatToShow 和 filter 的职责
document.createTreeWalker(root, whatToShow, filter) 的第二个参数是无符号整数位掩码,可以组合 NodeFilter 上的常量。它筛的是节点类型,例如元素、文本、注释或文档节点;它不是用来判断某个元素是否带有 data-role 属性的。
第三个参数可以是函数,也可以是带 acceptNode() 方法的对象。它只会接收已经被 whatToShow 纳入候选范围的节点,所以“先类型、后业务”是两个参数的自然分工。

用 NodeFilter 常量组合节点类型
常见的组合是按位或,而不是把业务条件直接塞进数字:
const walker = document.createTreeWalker(
document.body,
NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
null,
);
// 只遍历元素和文本节点,注释节点不会成为候选对象。
let node;
while ((node = walker.nextNode())) {
console.log(node.nodeType, node.nodeName);
}
SHOW_ELEMENT 的值是 0x1,SHOW_TEXT 是 0x4,组合后每一位仍然代表一种类型。常见常量还包括 SHOW_COMMENT、SHOW_DOCUMENT 和 SHOW_DOCUMENT_FRAGMENT。SHOW_ALL 表示全部节点类型,但不等于“所有节点都会被最终返回”,因为后面仍可能有 filter。
读取 TreeWalker.whatToShow 时看什么
whatToShow 是 TreeWalker 的只读属性,返回创建时使用的非负整数。你可以拿它与 NodeFilter.SHOW_ALL 比较,或者用位运算检查某一种类型是否被选中:
const walker = document.createTreeWalker( document.body, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT, ); // 用掩码检查元素类型是否在候选集合中。 const showsElement = walker.whatToShow === NodeFilter.SHOW_ALL || (walker.whatToShow & NodeFilter.SHOW_ELEMENT) !== 0; console.log(walker.whatToShow, showsElement);
这里用的是“掩码包含关系”,不是把返回值当作节点数量。比如元素和注释的组合值只说明两种类型被选择,不说明 DOM 中恰好有两个节点。属性节点也有对应常量,但在普通元素根节点的遍历中不能靠 nextNode() 遍历属性;需要读取 Element.attributes。
filter 负责自定义条件,返回值决定边界
当类型范围确定后,过滤器才适合处理业务条件。下面的例子只保留有文本内容的文本节点,同时跳过带 data-skip 的元素及其后代:
const walker = document.createTreeWalker(
document.body,
NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
(node) => {
// 业务条件只处理已通过 whatToShow 的节点。
if (node.nodeType === Node.TEXT_NODE) {
return node.data.trim()
? NodeFilter.FILTER_ACCEPT
: NodeFilter.FILTER_REJECT;
}
// REJECT 会把当前元素和它的子树一起排除。
if (node.nodeType === Node.ELEMENT_NODE && node.hasAttribute('data-skip')) {
return NodeFilter.FILTER_REJECT;
}
// 元素本身不作为结果,但仍允许继续看它的后代。
return NodeFilter.FILTER_SKIP;
},
);
let node;
while ((node = walker.nextNode())) {
// 这里拿到的是最终被 TreeWalker 接受的节点。
console.log(node.nodeName, node.textContent);
}
对 TreeWalker 来说,三种返回值的差别在于当前节点和后代子树:
| 返回值 | 当前节点 | 后代子树 | 典型用途 |
|---|---|---|---|
FILTER_ACCEPT | 进入遍历结果 | 仍可继续遍历 | 保留符合条件的节点 |
FILTER_SKIP | 不进入结果 | 继续检查 | 只想穿过容器元素 |
FILTER_REJECT | 不进入结果 | 整棵子树排除 | 明确切断某个分支 |

三个容易写错的判断
把 whatToShow 当成 CSS 选择器
whatToShow 不能表达“所有带某个属性的元素”或“文本长度大于 10”。这些属于节点内容或属性条件,应放进 filter。如果类型一开始就不在掩码里,过滤器没有机会把它“重新加入”。
只返回 FILTER_SKIP 来隐藏整个分支
FILTER_SKIP 只跳过当前节点,后代仍有机会被遍历。要切断整个分支,需要 FILTER_REJECT。这也是目录、评论容器或模板占位节点处理中最重要的区别。
把 whatToShow 的数字当成顺序或数量
位掩码的数字只编码类型集合。判断元素是否启用,应使用按位与;判断过滤结果,则看回调返回的 FILTER_* 常量。两者都是数字,但语义完全不同。
按“类型—业务—子树”组织可复用代码
实际项目里可以把判断顺序固定下来:先在 whatToShow 选择需要的节点类型,再在 filter 中写业务条件,最后只在确实不需要访问后代时使用 FILTER_REJECT。这样既减少无关节点进入回调,也避免把一个容器节点的展示规则误写成整棵子树的规则。
如果只是想收集文本,通常选择 SHOW_TEXT,用 FILTER_REJECT 排除空白文本;如果要穿过某类容器但不把容器本身放入结果,就返回 FILTER_SKIP;如果要彻底忽略一个分支,再返回 FILTER_REJECT。这套划分比在遍历循环内部再写一层节点类型分支更容易维护。
速查:什么时候改哪个参数
| 需求 | 优先修改 | 判断方式 |
|---|---|---|
| 只看元素或文本 | whatToShow | 组合 NodeFilter.SHOW_* |
| 按属性、类名或文本内容筛选 | filter | 返回 FILTER_ACCEPT 或跳过 |
| 不返回容器但继续看孩子 | filter | 返回 FILTER_SKIP |
| 整个分支都不需要 | filter | 返回 FILTER_REJECT |
| 确认创建时选择了哪些类型 | walker.whatToShow | 按位与常量,或比较 SHOW_ALL |
相关问题
whatToShow 没有设置时默认是什么?
省略该参数时默认使用表示全部节点类型的 SHOW_ALL。但自定义过滤器仍可能拒绝或跳过节点。
FILTER_REJECT 和 FILTER_SKIP 在 TreeWalker 中一样吗?
不一样。FILTER_SKIP 不返回当前节点但继续检查后代,FILTER_REJECT 会把当前节点及其子树一起排除。
可以在 filter 中改变 whatToShow 吗?
不可以。whatToShow 是只读属性;需要改变节点类型范围时,应重新创建一个使用新掩码的 TreeWalker。
-
130 收藏
-
306 收藏
-
194 收藏
-
414 收藏
-
427 收藏
-
145 收藏
-
243 收藏
-
341 收藏
-
216 收藏
-
337 收藏
-
文章 · 前端 | 4小时前 | html · 前端 · javascript · 表单 · SecurityError HTMLInputElement showPicker Transient activation NotAllowedError367 收藏
-
150 收藏
-
262 收藏
-
236 收藏
-
355 收藏
-
100 收藏
-
222 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习