Skip to main content

IntersectionObserver 🧪

预览版 🧪

此 API 目前仅在 React Native 的 Canary 和 Experimental 渠道中可用。

¥This API is currently only available in React Native’s Canary and Experimental channels.

如果你想尝试，请在你的应用中使用 启用 Canary 版本通道。

¥If you want to try it out, please enable the Canary Channel in your app.

Web 规范中定义的全局 IntersectionObserver 接口。它提供了一种异步观察目标元素与其祖级元素或顶层文档视口交集变化的方法。

¥The global IntersectionObserver interface, as defined in Web specifications. It provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport.

参考

¥Reference

构造函数​

¥Constructor

IntersectionObserver()​

参见 MDN 中的文档。

¥See documentation in MDN.

创建一个新的 IntersectionObserver 对象，当检测到目标元素的可见性超过一个或多个 threshold 或 rnRootThreshold 值时，该对象将执行指定的回调函数。

¥Creates a new IntersectionObserver object which will execute a specified callback function when it detects that a target element's visibility has crossed one or more threshold or rnRootThreshold values.

ts
new IntersectionObserver(callback, options?)

参数​

¥Parameters

callback

当目标元素的可见百分比超过阈值时调用的函数。回调函数接收两个参数：

¥A function which is called when the percentage of the target element is visible crosses a threshold. The callback receives two parameters:

  • entries：一个 IntersectionObserverEntry 对象数组，每个对象代表一个被跨越的阈值，其可见度会超过或低于该阈值指定的百分比。

    ¥entries: An array of IntersectionObserverEntry objects, each representing one threshold which was crossed, either becoming more or less visible than the percentage specified by that threshold.

  • observer：调用回调的 IntersectionObserver 实例。

    ¥observer: The IntersectionObserver instance which invoked the callback.

options（可选）

¥options (optional)

一个可选对象，包含以下属性：

¥An optional object with the following properties:

名称类型描述
root元素 |空目标的祖级元素，其边界矩形将被视为视口。如果未指定或为 null，则默认为根视口。
rootMarginstring一个字符串，用于指定计算交集时要添加到根节点边界框​​的偏移量。默认为 "0px 0px 0px 0px"。
thresholdnumber | number[]可以是单个数字或介于 0.0 和 1.0 之间的数字数组，用于指定观察目标的交集区域与边界框总面积的比率。如果未设置 rnRootThreshold，则默认为 [0]。
rnRootThreshold ⚠️number | number[]React Native 特有。可以是单个数字或介于 0.0 和 1.0 之间的数字数组，用于指定交集区域与根区域总面积的比率。

实例属性​

¥Instance properties

root​

参见 MDN 中的文档。

¥See documentation in MDN.

用于测试交集的边界框的元素或文档。

¥The element or document whose bounds are used as the bounding box when testing for intersection.

rootMargin​

参见 MDN 中的文档。

¥See documentation in MDN.

计算交集时应用于根节点边界框​​的偏移矩形。

¥An offset rectangle applied to the root's bounding box when calculating intersections.

rnRootThresholds ⚠️​

非标准

这是 React Native 特有的扩展。

¥This is a React Native specific extension.

一个根阈值列表，按数值升序排列，每个阈值是交叉区域与指定根视图（默认为视口）边界框区域的比率。

¥A list of root thresholds, sorted in increasing numeric order, where each threshold is a ratio of intersection area to bounding box area of the specified root view, which defaults to the viewport.

当目标的 rnRootThresholds 或 thresholds 中指定的任何阈值被超过时，就会生成该目标的通知。

¥Notifications for a target are generated when any of the thresholds specified in rnRootThresholds or thresholds are crossed for that target.

ts
get rnRootThresholds(): ReadonlyArray<number> | null;

thresholds​

参见 MDN 中的文档。

¥See documentation in MDN.

一个阈值列表，按数值升序排列，每个阈值表示观测目标的交集区域与其边界框区域的比值。

¥A list of thresholds, sorted in increasing numeric order, where each threshold is a ratio of intersection area to bounding box area of an observed target.

当目标的 rnRootThresholds 或 thresholds 中指定的任何阈值被超过时，就会生成该目标的通知。

¥Notifications for a target are generated when any of the thresholds specified in rnRootThresholds or thresholds are crossed for that target.

实例方法​

¥Instance methods

disconnect()​

参见 MDN 中的文档。

¥See documentation in MDN.

停止 IntersectionObserver 对象观察任何目标。

¥Stops the IntersectionObserver object from observing any target.

observe()​

参见 MDN 中的文档。

¥See documentation in MDN.

指示 IntersectionObserver 开始观察某个目标元素。

¥Tells the IntersectionObserver to begin observing a target element.

takeRecords()​

参见 MDN 中的文档。

¥See documentation in MDN.

返回一个包含所有已观察目标的 IntersectionObserverEntry 对象数组。

¥Returns an array of IntersectionObserverEntry objects for all observed targets.

unobserve()​

参见 MDN 中的文档。

¥See documentation in MDN.

指示 IntersectionObserver 停止观察某个特定目标元素。

¥Tells the IntersectionObserver to stop observing a particular target element.