登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  文章 >  前端

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 纳入候选范围的节点,所以“先类型、后业务”是两个参数的自然分工。

DOM 根节点、TreeWalker、whatToShow 位掩码与 filter 回调之间的静态关系
图1:whatToShow 与 filter 的分层关系说明图,不是浏览器运行截图。

用 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不进入结果整棵子树排除明确切断某个分支
FILTER_ACCEPT、FILTER_SKIP、FILTER_REJECT 对当前节点和后代子树的静态边界
图2:三种 FILTER 返回值与节点子树边界的关系说明图,不是浏览器运行截图。

三个容易写错的判断

把 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。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>