NodeIterator 怎样在文本节点之间遍历并保留当前游标

做正文查找、局部高亮或无障碍朗读时，我更愿意先拿到文本节点，再决定怎么处理它们。NodeIterator 正适合这个场景：它按文档顺序走过一棵 DOM 子树，当前位置不是数组下标，而是由 referenceNode 和 pointerBeforeReferenceNode 一起表达。这样向前、向后切换时，游标仍然有明确含义。

NodeIterator 的游标不是数组下标

先准备一段带嵌套元素的内容。document.createNodeIterator(root, whatToShow, filter) 的第一个参数是遍历根，第二个参数决定关注哪些节点类型，第三个参数可以返回 FILTER_ACCEPT 或 FILTER_REJECT。只遍历文本时，最小配置如下：

const article = document.querySelector('#article');

// 只观察文本节点，元素节点仍作为树结构参与定位。
const iterator = document.createNodeIterator(
  article,
  NodeFilter.SHOW_TEXT,
  {
    acceptNode(node) {
      // 去掉纯空白文本，避免高亮或朗读列表出现空项。
      return node.nodeValue.trim()
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT;
    }
  }
);

const firstText = iterator.nextNode();
console.log(firstText?.nodeValue ?? '没有可用文本');

这里的“当前”不是 firstText 变量本身。每次调用 nextNode() 或 previousNode()，遍历器都会更新内部锚点。referenceNode 指向锚定节点，pointerBeforeReferenceNode 为 true 时表示游标在它前面，为 false 时表示游标在它后面。

用 whatToShow 与 filter 把遍历范围收窄

这两个参数职责不同，混在一起是最容易误判结果的地方。SHOW_TEXT 是节点类型掩码；它不会检查文本是否为空，也不会把多个文本节点合并。filter 才适合表达“只保留有实际字符的文本”“跳过代码块”等应用条件。

例如查找关键词时，不要在过滤器里修改 DOM。过滤器最好是轻量、可重复调用的判断函数；真正的高亮、滚动或标记放到遍历完成后执行。这样既不会让过滤过程改变下一次遍历的边界，也更容易测试。

把当前位置变成可以恢复的状态

如果界面有“下一个匹配”和“上一个匹配”两个按钮，可以复用同一个迭代器，而不是每次从根节点重新开始。循环结束后，方法返回 null；这时应把按钮置灰，不要把 null 当作游标节点继续读属性。

function move(iterator, direction) {
  // 两个方向消费同一个遍历器，返回 null 就代表到达边界。
  const node = direction === 'next'
    ? iterator.nextNode()
    : iterator.previousNode();

  if (!node) {
    return { node: null, label: '已经到达边界' };
  }

  // 只把文本内容交给界面层，避免把 DOM 节点直接拼进提示语。
  return { node, label: node.nodeValue.trim() };
}

const saved = {
  // 保存引用和前后状态，便于同一轮交互中显示当前位置。
  referenceNode: iterator.referenceNode,
  before: iterator.pointerBeforeReferenceNode
};

这个状态只对当前 DOM 树有意义。若框架重新渲染并替换了文本节点，旧引用可能已经脱离原树；此时不要强行恢复旧迭代器，应以新的根节点重建它，并根据业务键或文本偏移重新定位。若只需一次性收集结果，可在遍历结束后保存字符串数组，避免把大量节点引用长期留在状态管理器里。

无障碍、性能与边界状态

文本查找结果应同步到可访问的状态区域，例如用 aria-live="polite" 告知“已找到第 2 个匹配项”，并让键盘用户能触发前后移动。不要只依赖背景色高亮，也不要把隐藏文本、脚本节点或纯空白节点交给朗读层。

• 小内容：边遍历边处理即可，不必预先复制整棵树。
• 大内容：过滤器避免正则和布局读取；高亮操作集中批量执行，减少反复触发布局。
• 节点删除：当前节点被移除后，下一步结果取决于新的树关系，需把“无结果”作为正常分支。
• 方向切换：先明确按钮语义，再决定调用 nextNode() 还是 previousNode()，不要用数组索引模拟。

延伸问答

NodeIterator 会遍历元素节点吗？

默认可以观察多种节点，但把 whatToShow 设为 SHOW_TEXT 后，返回结果只会是文本节点；元素仍然存在于遍历树中，只是不作为匹配结果返回。

为什么过滤器返回 REJECT 后没有文本？

对 NodeIterator 来说，被拒绝的节点不会作为结果返回。若你的目标是跳过节点本身但仍允许检查其后代，应重新检查过滤条件，避免把不该排除的子树一起挡住。

NodeIterator 和 TreeWalker 怎么选？

只需要按文档顺序取匹配节点时选 NodeIterator；需要在当前节点上访问父子兄弟关系、主动控制树形移动时，TreeWalker 更合适。