30 seconds of code:用 JavaScript 判断元素是否在视口(viewport)内可见

原创2026-10-02 14:25:481,819 阅读
文章标签:教程文档

30 seconds of code:用 JavaScript 判断元素是否在视口(viewport)内可见

导读

在无限滚动加载、懒加载、滚动动画触发、"回到顶部"按钮显隐等场景中,判断一个 DOM 元素当前是否在浏览器视口内可见,是前端开发中最常见的高频需求之一。本文基于 30 seconds of code 仓库中的 element-is-visible-in-viewport.md 文档,系统讲解如何用 Element.getBoundingClientRect() 与 Window.innerWidth / Window.innerHeight 组合出零依赖的判断函数,支持"完全可见"与"部分可见"两种模式,并给出可复制、可直接运行的完整代码与边界情况分析。


为什么需要自己实现"元素是否可见"

浏览器并没有提供一个内置的、直接返回"元素是否在视口内"的 API。Element.getBoundingClientRect()、Window.innerWidth 等底层能力虽然都有,但都需要开发者自行组合与判断。这正是 30 seconds of code 将这一技巧整理为独立 snippet 的原因:用最少的代码,把常见需求封装成可复用的工具函数。

在仓库中,这一类"针对浏览器视口与布局的判断"被打包进 DOM 查询集合(dom-querying.yaml),与其并列的还有:

可见"元素在视口中的位置与可见性"是 DOM 查询领域的一类完整问题,而"元素是否可见"正是其中最基础、最常用的一个。


核心 API:三步拿到全部判断素材

判断元素是否可见,本质上是把"元素的几何位置"与"视口的几何尺寸"做一次比较。JavaScript 提供两组 API 分别解决这两件事。

1. 用 getBoundingClientRect() 获取元素坐标

Element.getBoundingClientRect() 返回一个 DOMRect 对象,它给出元素相对视口(而非文档)的坐标信息:

  • top / left / right / bottom:元素四条边相对于视口左上角的坐标;
  • width / height:元素的宽高;
  • 另外还包含 x / y 属性。

在文档示例中,通过对象解构(object destructuring)可以一次性取出我们需要的四个坐标:

const { top, left, bottom, right } = el.getBoundingClientRect();

需要特别注意的是:这里的坐标是相对于视口的,也就是说当页面发生滚动时,这些值会随之变化。这恰恰是我们做可见性判断想要的行为——我们关心的就是元素此刻在屏幕上的位置。

2. 用 innerWidth / innerHeight 获取视口尺寸

视口的宽高分别由 Window.innerWidth 与 Window.innerHeight 提供,表示浏览器窗口内部(不含滚动条)的可见区域尺寸。同样可以用解构一次取到:

const { innerHeight, innerWidth } = window;

3. 把两者放到同一个坐标系里比较

由于 getBoundingClientRect() 返回的坐标与视口使用同一坐标系(都以视口左上角为原点),我们可以直接把"元素四边坐标"与"视口宽高"进行大小比较,从而得到可见性结论。

从源码实现看,这一组合正是文档示例函数的核心逻辑:top / left / bottom / right 四值与 innerHeight / innerWidth 做区间比较,无需引入任何第三方库,也不依赖滚动事件。


两种可见性模式:完全可见与部分可见

"可见"在业务上通常有两种口径,文档示例函数通过一个可选的 partiallyVisible 参数来区分。

完全可见(fully visible)

当 partiallyVisible 为 false(默认值)时,要求元素四条边全部落在视口范围内:

top >= 0 && left >= 0 && bottom <= innerHeight && right <= innerWidth

即:

  • 上边不高于视口顶部(top >= 0);
  • 左边不左于视口左缘(left >= 0);
  • 下边不超出视口底部(bottom <= innerHeight);
  • 右边不超出视口右缘(right <= innerWidth)。

部分可见(partially visible)

当 partiallyVisible 为 true 时,只要元素任一部分进入视口即视为可见:

((top > 0 && top < innerHeight) || (bottom > 0 && bottom < innerHeight)) &&
((left > 0 && left < innerWidth) || (right > 0 && right < innerWidth))

这段逻辑可以拆成两层来看:

  • 垂直方向:元素的上边落在视口内(top > 0 && top < innerHeight),或下边落在视口内(bottom > 0 && bottom < innerHeight);
  • 水平方向:元素的左边落在视口内(left > 0 && left < innerWidth),或右边落在视口内(right > 0 && right < innerWidth);
  • 垂直与水平两个方向同时满足,才判定为部分可见。

换句话说,只有当元素完全在视口上方/下方/左侧/右侧(例如已经滚出屏幕)时,两个方向才不会同时满足,函数才会返回 false。

完整函数与运行示例

把以上逻辑封装起来,就是文档给出的完整实现:

const elementIsVisibleInViewport = (el, partiallyVisible = false) => {
  const { top, left, bottom, right } = el.getBoundingClientRect();
  const { innerHeight, innerWidth } = window;
  return partiallyVisible
    ? ((top > 0 && top < innerHeight) ||
        (bottom > 0 && bottom < innerHeight)) &&
        ((left > 0 && left < innerWidth) || (right > 0 && right < innerWidth))
    : top >= 0 && left >= 0 && bottom <= innerHeight && right <= innerWidth;
};

文档中给出的验证示例(100x100 视口 + 位于 {top: -1, left: 0, bottom: 9, right: 10} 的 10x10 元素):

elementIsVisibleInViewport(el); // false -(顶部越界 1px,未完全可见)
elementIsVisibleInViewport(el, true); // true -(仍有一部分落在视口内)

这个示例很好地展示了两种模式的差异:元素的 top 为 -1,意味着它上边已经超出视口顶部 1px。此时"完全可见"判定为 false(因为有 1px 被裁切),而"部分可见"判定为 true(因为下边 bottom = 9 仍落在 0 < bottom < 100 区间内)。


边界情况与注意事项

1. 元素尺寸大于视口

如果元素本身比视口还大(例如长图、整屏的 banner),那么"完全可见"永远为 false(bottom <= innerHeight 与 right <= innerWidth 无法同时成立)。此时应根据业务选择部分可见模式,或者引入"视口内的可见比例"等更精细的判断。

2. 与滚动监听配合使用

getBoundingClientRect() 返回的坐标随滚动实时变化,因此该函数通常是瞬时快照。若要持续跟踪可见性(例如做滚动动画触发),需要配合 scroll 事件或 requestAnimationFrame 周期性调用。对于性能敏感的大规模场景,也可以考虑用 IntersectionObserver 替代手动轮询,但它在部分老旧环境中的支持情况需要额外评估。

3. 坐标系与内联 iframe

坐标是相对视口的,若元素位于内嵌的 iframe 中,其 getBoundingClientRect() 结果相对的是 iframe 自身窗口,这一点与仓库中 element-from-point.md 提到的 Document.elementFromPoint() 行为类似,跨框架场景需要分别处理。

4. 返回值只反映"是否可见",不反映"可见多少"

该函数返回布尔值。如果业务需要"可见比例"(例如 50% 可见才触发动画),可以基于 top / bottom 与 innerHeight 自行计算交叠区间长度。

5. 相关但不同的技巧

仓库中还提供了两个与"视口/页面可见性"相关的函数,注意区分适用场景:

  • bottom-visible.md:判断页面底部是否可见,用于无限滚动加载、内容懒加载——它基于 Element.scrollHeight、Element.clientHeight 与 Window.scrollY,而非元素坐标比较;
  • get-elements-wider-than-viewport.md:找出比视口更宽的溢出元素,用于排查横向滚动条问题——它用 HTMLElement.offsetWidth 与文档宽度比较,是一个页面级的诊断工具。

三者组合起来,可以覆盖大部分"元素与视口关系"的判断需求。


典型应用场景

判断元素可见性最常见的落地场景包括:

  • 懒加载:图片或媒体元素进入视口后再加载资源;
  • 无限滚动 / 触底加载:底部占位元素可见时请求下一页数据(更轻量的做法可参考 bottom-visible.md);
  • 滚动动画触发:元素部分或完全进入视口时播放进场动画;
  • 吸顶 / "回到顶部"按钮:页面滚动到一定位置后显示操作按钮;
  • 广告曝光统计:统计广告位是否真正被用户看到。

以懒加载为例,最朴素的做法就是在 scroll 事件回调中调用该函数:

window.addEventListener('scroll', () => {
  if (elementIsVisibleInViewport(img, true)) {
    img.src = img.dataset.src; // 进入视口后再真正加载
  }
}, { passive: true });

小结

本文完整复现并讲解了 30 seconds of code 仓库中 element-is-visible-in-viewport.md 的核心技巧:通过 Element.getBoundingClientRect() 拿到元素相对视口的四边坐标,配合 Window.innerWidth / Window.innerHeight 的视口尺寸,用一组简单的区间比较同时支持"完全可见"与"部分可见"两种判定模式。整个实现零依赖、约 8 行代码,可直接复制进任何浏览器端项目使用。理解其坐标系统(相对视口)与布尔返回值的边界,是正确应用这一技巧的关键。

登录后查看全文
30-seconds-of-code