Back

如何通过文本查找 DOM 元素

OpenReplay Team OpenReplay Team

Mar 18, 2026 · 3 min read

如何通过文本查找 DOM 元素

DOM API 中没有 getElementByText() 方法。如果你需要根据元素的文本内容而非元素类型来定位元素,就必须自己构建这种能力。这种需求出现的频率比你想象的要高——自动化脚本、UI 测试、动态内容解析——而正确的方法取决于你需要多大的灵活性。

核心要点

  • DOM API 没有内置的按文本内容选择元素的方法,但有三种原生方法可以填补这一空白:使用 querySelectorAll 过滤、使用 TreeWalker 遍历,以及使用 XPath 查询。
  • TreeWalker 是最通用的原生选项,可以在任何元素类型上进行全 DOM 文本搜索,而无需预先收集大型 NodeList。
  • 在文本匹配时优先使用 textContent 而非 innerText——它更快,避免触发布局重计算,并且无论元素可见性如何都能保持一致的行为。
  • 注意常见陷阱,如额外的空白字符、嵌套的后代文本,以及可能在脚本运行时尚未存在的动态注入内容。

为什么 querySelector 无法通过文本内容查询 DOM

querySelector() 和 querySelectorAll() 只接受 CSS 选择器。虽然 CSS 有 :has() 伪类和属性选择器,但没有标准的 CSS 选择器可以匹配元素的文本内容。像 div:text("Submit") 这样的选择器在规范中根本不存在。

这就给你留下了三种实用的方法:过滤候选集合、使用原生 API 遍历 DOM,或使用 XPath。

方法 1:按文本过滤候选集合

最简单的方法是通过标签或类查询元素,然后按文本过滤。当你预先知道元素类型时,这种方法效果很好。

function findByText(tag, text) {
  return [...document.querySelectorAll(tag)].filter(el =>
    el.textContent.trim() === text
  )
}

// 使用示例
const buttons = findByText('button', 'Submit')

当候选集合较小时,这种方法可读性好且速度快。缺点是:它一次只能搜索一种元素类型。使用 '*' 搜索所有元素虽然可行,但在大型 DOM 上速度较慢。

方法 2:使用 TreeWalker 遍历 DOM

TreeWalker 是一个内置的 DOM API,可以让你高效地遍历节点。它在所有现代浏览器中都得到良好支持,并且避免了预先收集完整 NodeList 的开销。

function findElementsByText(root, text) {
  const walker = document.createTreeWalker(
    root,
    NodeFilter.SHOW_ELEMENT,
    {
      acceptNode(node) {
        return node.textContent.trim() === text
          ? NodeFilter.FILTER_ACCEPT
          : NodeFilter.FILTER_SKIP
      }
    }
  )

  const results = []
  while (walker.nextNode()) results.push(walker.currentNode)
  return results
}

// 使用示例
const matches = findElementsByText(document.body, 'TV')

这种方法可以在整个树中搜索任何元素类型——这是特定标签方法无法提供的通用解决方案。它还支持提前终止,如果你只需要第一个匹配项的话。

关于 FILTER_SKIP 与 FILTER_REJECT 的说明: 这里使用 FILTER_SKIP 意味着遍历器仍会深入到不匹配节点的子节点中。如果你使用 FILTER_REJECT,遍历器会跳过该节点及其整个子树。对于文本搜索,FILTER_SKIP 几乎总是你想要的,因为即使父节点的 textContent 可能不匹配,更深层后代节点的内容可能会匹配。

方法 3:在 DOM 中使用 XPath 文本搜索

对于更具表达力的匹配,document.evaluate() 支持 XPath 表达式,包括基于文本的查询。这是处理复杂模式最强大的选项。

function findByXPath(expression, context = document) {
  const result = document.evaluate(
    expression,
    context,
    null,
    XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
    null
  )

  return Array.from({ length: result.snapshotLength }, (_, i) =>
    result.snapshotItem(i)
  )
}

// 查找任何包含文本 "Submit" 的元素
const els = findByXPath('//*[contains(text(), "Submit")]')

DOM 中的 XPath 文本搜索可以干净地处理部分匹配和复杂条件。权衡之处在于可读性——大多数前端开发者对 XPath 语法不太熟悉。

需要记住的一点:contains(text(), "Submit") 只匹配元素的直接文本节点。如果 “Submit” 位于子元素内部,这个表达式不会匹配父元素。要搜索所有后代文本,请改用 contains(., "Submit"),其中 . 指的是整个元素(包括其后代)的字符串值。

textContent 与 innerText:匹配时该使用哪个

这两个属性都返回文本,但它们的行为不同:

属性返回内容是否触发布局?
textContent原始 DOM 文本,包括隐藏元素否
innerText仅渲染的文本是(回流)

使用 textContent 进行文本匹配。它更快,不会触发布局重计算,并且无论元素可见性如何都能在所有元素上保持一致工作。

通过文本查找 DOM 元素时的常见陷阱

空白字符: textContent 包含来自 HTML 格式化的空白字符。比较前始终使用 .trim()。

嵌套文本: 元素的 textContent 包含所有后代文本。<div><span>TV</span></div> —— div 的 textContent 也是 "TV"。要明确你针对的是哪个元素层级。

动态内容: 页面加载后注入的文本在脚本运行时不会存在。使用 MutationObserver 或在确认内容存在后运行搜索。

选择正确的方法

  • 已知元素类型,简单匹配 → 使用 querySelectorAll 过滤
  • 任何元素类型,全 DOM 搜索 → TreeWalker
  • 部分匹配或复杂模式 → 通过 document.evaluate() 使用 XPath

如果你在测试环境中工作,Testing Library 等工具提供了内置的 getByText() 方法——值得了解,尽管上述原生技术对于非测试脚本仍然至关重要。

总结

基于文本的 DOM 查找是标准 API 中的一个空白,但这三种方法涵盖了所有实际情况。当你知道元素类型时,使用带过滤器的 querySelectorAll 进行快速、有针对性的搜索。当你需要完整的 DOM 遍历而不想限定特定标签时,使用 TreeWalker。当匹配逻辑需要部分文本或复杂条件时,使用 XPath。无论选择哪种方法,都要优先使用 textContent 而非 innerText,比较前修剪空白字符,并考虑嵌套的后代文本以避免错误匹配。

常见问题

不可以。querySelector 和 querySelectorAll 只接受 CSS 选择器,而 CSS 没有用于匹配文本内容的选择器。你需要使用基于 JavaScript 的方法,例如过滤 querySelectorAll 结果集、使用 TreeWalker 遍历 DOM,或使用 document.evaluate 运行 XPath 表达式来根据元素包含的内容定位元素。

FILTER_SKIP 告诉 TreeWalker 跳过当前节点但仍然访问其子节点。FILTER_REJECT 跳过该节点及其整个子树。对于基于文本的搜索,FILTER_SKIP 通常是正确的选择,因为父节点可能不匹配,但更深层的后代可能会匹配。

不会。表达式 contains(text(), value) 只检查元素的直接文本节点。如果目标字符串位于嵌套的子元素内,请改用 contains(., value)。点运算符指的是元素的完整字符串值,包括所有后代文本。

textContent 更快,因为它不会触发布局回流。它返回 DOM 子树中的所有文本,无论 CSS 可见性如何,使其保持一致和可预测。innerText 只返回渲染的文本,并强制浏览器重新计算布局,这为匹配目的增加了不必要的开销。

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.

OpenReplay

More articles from OpenReplay Blog