30 seconds of code:用 JavaScript 判断元素是否在视口(viewport)内可见
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),与其并列的还有:
- get-elements-wider-than-viewport.md:找出比视口更宽的溢出元素;
- element-from-point.md:获取页面指定坐标处的元素;
- get-vertical-offset.md:计算元素到文档顶部的垂直偏移量。
可见"元素在视口中的位置与可见性"是 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 行代码,可直接复制进任何浏览器端项目使用。理解其坐标系统(相对视口)与布尔返回值的边界,是正确应用这一技巧的关键。