react-use 的 useIntersection：用 Intersection Observer API 感知元素可见性

react-use 的 useIntersection：用 Intersection Observer API 感知元素可见性

【免费下载链接】react-useReact Hooks — 👍项目地址: https://gitcode.com/gh_mirrors/re/react-use

导读

useIntersection是 react-use 提供的一个传感器（Sensor）类 React Hook，它封装了浏览器原生的 Intersection Observer API，用于实时追踪目标元素与祖先元素或顶级文档视口之间的交叉（intersection）变化，并返回最新的IntersectionObserverEntry对象。本文将以 docs/useIntersection.md 为核心，结合仓库中的源码实现、单元测试与 Storybook 示例，讲解该 Hook 的用法、参数语义、运行机制与边界行为，帮助你用十几行代码实现"元素是否进入视口""滚动到某处触发加载""曝光埋点"等典型场景。

什么是 useIntersection

在 react-use 的 Sensor Hooks 体系（参见 docs/Sensors.md）中，useIntersection负责监听某个界面事件并驱动组件以最新状态重新渲染。它跟踪的是目标元素与某个祖先元素或顶级文档视口之间的交叉情况，底层完全建立在浏览器原生的 Intersection Observer API 之上。

其核心特性如下：

• 跟踪目标元素与根元素（root）之间的交叉区域变化；
• 返回值为IntersectionObserverEntry（或其null变体），可直接读取intersectionRatio、isIntersecting等字段；
• 无需手动维护 observer 的创建、观察与断开，全部由 Hook 内部管理；
• 依赖数组对ref.current与关键选项进行监听，目标元素或选项变化时会自动重建 observer。

函数签名

useIntersection( ref: RefObject<HTMLElement>, options: IntersectionObserverInit, ): IntersectionObserverEntry | null;

• ref：指向目标 DOM 元素的RefObject<HTMLElement>。当ref.current尚未绑定元素（例如组件首次渲染时）或元素不存在时，Hook 返回null。
• options：原生IntersectionObserverInit配置对象，包括root、rootMargin与threshold（详见下文参数说明）。
• 返回值：最新一次的IntersectionObserverEntry；在 observer 尚未触发任何回调、目标元素缺失或浏览器不支持 IntersectionObserver 时为null。

快速上手

安装

react-use 以 npm 包形式分发，可通过 yarn 或 npm 安装：

yarn add react-use # 或 npm install react-use

从源码结构看，包通过 src/index.ts 的export { default as useIntersection } from './useIntersection';对外导出，因此可直接命名导入：

import { useIntersection } from 'react-use';

基础示例：判断元素是否完整可见

以下示例直接取自 docs/useIntersection.md，创建一个始终引用目标元素的 ref，并把threshold设为1（要求 100% 可见才视为"完整在视口内"）：

import * as React from 'react'; import { useIntersection } from 'react-use'; const Demo = () => { const intersectionRef = React.useRef(null); const intersection = useIntersection(intersectionRef, { root: null, rootMargin: '0px', threshold: 1 }); return ( <div ref={intersectionRef}> {intersection && intersection.intersectionRatio < 1 ? 'Obscured' : 'Fully in view'} </div> ); };

当元素被滚动遮挡时，intersectionRatio会小于1，界面显示Obscured；元素完整进入视口后显示Fully in view。注意intersection初始为null，因此渲染分支中要先做intersection &&的空值判断。

带滚动容器的完整演示

仓库中的 Storybook 示例 stories/useIntersection.story.tsx 给出了一个更接近真实布局的用法：外层是一个可滚动的div（充当交叉区域），目标元素嵌套在多个占位块之间，滚动外层容器即可看到目标元素在Obscured与Fully in view之间切换：

const Demo = () => { const intersectionRef = React.useRef(null); const intersection = useIntersection(intersectionRef, { root: null, rootMargin: '0px', threshold: 1, }); return ( <div style={{ width: '400px', height: '400px', backgroundColor: 'whitesmoke', overflow: 'scroll', }}> Scroll me <Spacer /> <div ref={intersectionRef} style={{ width: '100px', height: '100px', padding: '20px', backgroundColor: 'palegreen', }}> {intersection && intersection.intersectionRatio < 1 ? 'Obscured' : 'Fully in view'} </div> <Spacer /> </div> ); };

该 Story 同时演示了Docs页（通过ShowDocs渲染docs/useIntersection.md原文），是理解本 Hook 行为的最佳交互式参考。你可以在仓库根目录运行yarn storybook（对应 package.json 中的start/storybook脚本，默认端口 6008）后，在Sensors/useIntersection分组下查看。

options 参数详解

useIntersection的第二个参数直接透传给原生IntersectionObserver，因此其语义与浏览器规范一致：

需要注意，与原生 API 的默认值不同，文档示例中通常显式写出root: null与rootMargin: '0px'，这样能保证跨浏览器行为一致。

源码实现与运行机制

useIntersection的完整实现位于 src/useIntersection.ts，仅有约 28 行，其运行逻辑可以拆解为以下几步。

状态管理

Hook 使用useState<IntersectionObserverEntry | null>保存最近一次交叉回调带来的 entry：

const [intersectionObserverEntry, setIntersectionObserverEntry] = useState<IntersectionObserverEntry | null>(null);

初始值为null，这与"尚未产生任何交叉数据"的语义一致，也解释了为何返回值类型包含null。

observer 的创建与清理

在useEffect中，Hook 首先检查ref.current是否存在、以及浏览器是否支持IntersectionObserver：

useEffect(() => { if (ref.current && typeof IntersectionObserver === 'function') { const handler = (entries: IntersectionObserverEntry[]) => { setIntersectionObserverEntry(entries[0]); }; const observer = new IntersectionObserver(handler, options); observer.observe(ref.current); return () => { setIntersectionObserverEntry(null); observer.disconnect(); }; } return () => {}; }, [ref.current, options.threshold, options.root, options.rootMargin]);

几个值得注意的实现细节：

• 回调只取第一条 entry：Intersection Observer 的回调会收到一个 entry 数组，而本 Hook 只观察了一个目标元素，因此直接取entries[0]并写入 state，从而触发组件重新渲染；
• useEffect 返回清理函数：每次 effect 重跑前都会执行setIntersectionObserverEntry(null)重置状态，并调用observer.disconnect()断开旧的 observer，避免内存泄漏；
• 依赖数组精挑细选：依赖项为ref.current与options.threshold、options.root、options.rootMargin，而非整个options对象。从源码结构看，这是为了在传入内联对象字面量时避免因引用变化而无谓地重建 observer；与此同时，这也意味着修改options上的其他字段不会被感知，实际使用时应只变更这四个受监听的关键配置；
• 能力检测：typeof IntersectionObserver === 'function'的守卫确保在不支持该 API 的浏览器环境中安全降级，此时 Hook 不做任何观察、返回null，不会抛错。

目标元素与配置变化时的行为

由于依赖数组的存在，当发生以下任一情况时，Hook 会断开旧 observer、清空 entry 并针对新的目标或配置重新建立 observer：

• ref.current从无到有、从有到无、或切换到另一个 DOM 元素；
• threshold、root或rootMargin任一值变化。

这一点在下文的测试用例中得到了充分验证。

边界行为：来自单元测试的证据

仓库中的 tests/useIntersection.test.tsx 使用@shopify/jest-dom-mocks模拟了 Intersection Observer，并通过renderHook验证了本 Hook 的关键边界行为，可以作为理解其语义的权威参考：

其中"目标元素变化时 entry 被重置为null"这一点尤其值得注意：当你在列表渲染中复用同一个 Hook 而目标元素切换时，界面不会短暂地显示上一个元素的交叉状态，而是回到"未知"状态，这避免了错误的可见性判断。

典型实战场景

基于上述 API 与行为，useIntersection可快速实现以下常见需求：

1. 图片/内容懒加载：监听目标占位元素，当intersectionRatio > 0或isIntersecting为真时再加载真实资源；
2. 无限滚动：在列表底部放置一个哨兵元素，进入视口即触发下一页数据请求；
3. 曝光埋点：元素可见比例超过阈值（如 50%）时上报一次曝光事件；
4. 吸顶/动画触发：根据intersectionRatio判断元素被遮挡程度，动态切换样式或播放动画；
5. 阅读进度提示：组合threshold: [0, 0.25, 0.5, 0.75, 1]数组，获得更细粒度的可见比例回调。

注意事项

• 浏览器兼容性：本 Hook 依赖原生 Intersection Observer API，不支持的环境（如部分旧版移动端浏览器）下会静默返回null。需要全兼容时，可自行在应用层引入 polyfill；
• options对象引用：依赖数组只监听threshold、root、rootMargin三个字段，更新options中的其他属性不会被响应；
• 初始为null：渲染时必须处理intersection === null的情况（如显示占位内容），避免读取intersection.intersectionRatio报错；
• 服务端渲染（SSR）：由于依赖浏览器 API，在 SSR 环境下 effect 不会执行，Hook 返回null，这与项目提供的test:ssr测试脚本（见 package.json）所覆盖的整体策略一致。

小结

useIntersection是 react-use 中封装度极高、实现极简（约 28 行源码）的传感器 Hook：它把 Intersection Observer 的创建、观察、状态同步与清理全部收敛进一个 Hook 中，并妥善处理了目标元素缺失、浏览器不支持、选项变更等边界场景。无论是滚动驱动的可见性判断，还是懒加载与曝光埋点，都可以通过本文的示例与参数说明直接落地到业务代码中。如需深入验证其行为，可结合 src/useIntersection.ts、tests/useIntersection.test.tsx 与 stories/useIntersection.story.tsx 一起阅读。

【免费下载链接】react-useReact Hooks — 👍项目地址: https://gitcode.com/gh_mirrors/re/react-use