From 04c2735735240968800677bf4fe8155b461dcbbe Mon Sep 17 00:00:00 2001 From: A1lo Date: Mon, 23 Dec 2024 14:49:33 +0800 Subject: [PATCH] zh-cn: update the translation of `IntersectionObserver.observe()` (#25162) --- .../api/intersectionobserver/observe/index.md | 35 +++++++++++-------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/files/zh-cn/web/api/intersectionobserver/observe/index.md b/files/zh-cn/web/api/intersectionobserver/observe/index.md index 03f95ba93303dc..3d08c79ce5ef1e 100644 --- a/files/zh-cn/web/api/intersectionobserver/observe/index.md +++ b/files/zh-cn/web/api/intersectionobserver/observe/index.md @@ -1,48 +1,53 @@ --- -title: IntersectionObserver.observe() +title: IntersectionObserver：observe() 方法 slug: Web/API/IntersectionObserver/observe +l10n: + sourceCommit: 4dec42ed700040565e8af0e14ff104054ebc20f5 --- {{APIRef("Intersection Observer API")}} -{{domxref("IntersectionObserver")}} 对象的**`observe()`** 方法向 IntersectionObserver 对象监听的目标集合添加一个元素。一个监听者有一组阈值和一个根，但是可以监视多个目标元素，以查看这些目标元素可见区域的变化。调用{{domxref("IntersectionObserver.unobserve()")}}方法可以停止观察元素。 +{{domxref("IntersectionObserver")}} 的 **`observe()`** 方法向 `IntersectionObserver` 对象观察的目标集合添加一个元素。一个观察者有一组阈值和一个根（root），但是可以监视多个目标元素的可见性变化（遵循阈值和根的设置）。 -当指定元素的可见区域超过监听者的可见区域阈值之一时（阈值列表{{domxref("IntersectionObserver.thresholds")}}），监听者的回调会被传入代表当前发生的交叉变化{{domxref("IntersectionObserverEntry")}}并执行。请注意，这种设计允许通过调用一次回调，给回调传入 IntersectionObserverEntry 对象数组，来实现同时处理多个被监听元素的交叉变化。 +调用 {{domxref("IntersectionObserver.unobserve()")}} 方法可以停止观察元素。 + +当指定元素的可见区域超过观察者的可见区域阈值（在 {{domxref("IntersectionObserver.thresholds")}} 中列出）之一时，观察者的回调会被执行并传入代表当前发生的交叉变化的 {{domxref("IntersectionObserverEntry")}} 对象数组。请注意，这种设计允许通过一次回调调用来处理多个元素的交叉变化。 + +> [!NOTE] +> 观察器的[回调](/zh-CN/docs/Web/API/IntersectionObserver/IntersectionObserver#callback)总是会在调用 `observe()` 后的第一个渲染周期中触发，即使观察的元素相对于视口尚未移动。这意味着，例如，当在视口之外的元素上调用 `observe()` 时，回调将立即被调用且至少会有一个 [`intersecting`](/zh-CN/docs/Web/API/IntersectionObserverEntry/isIntersecting) 被设置为 `false` 的[条目](/zh-CN/docs/Web/API/IntersectionObserverEntry)。在视口内的元素将导致回调立即被调用且至少有一个 `intersecting` 被设置为 `true` 的条目。 ## 语法 -```js -IntersectionObserver.observe(targetElement); +```js-nolint +observe(targetElement) ``` ### 参数 - `targetElement` - - : 可见性区域被监控的元素{{domxref("element")}}。 - 此元素必须是根元素的后代 (如果根元素为视窗，则该元素必须被当前文档包含)。 + - : 要监视其在根范围内的可见性的{{domxref("element", "元素", "", 1)}}。此元素必须是根元素的后代（或者如果根是文档的视口，则该元素必须被包含在当前文档中）。 ### 返回值 -`undefined`. +无（{{jsxref("undefined")}}）。 ## 示例 ```js -// Register IntersectionObserver +// 注册 IntersectionObserver const io = new IntersectionObserver((entries) => { entries.forEach((entry) => { - // Add 'active' class if observation target is inside viewport if (entry.intersectionRatio > 0) { + // 如果观察目标在视口内，则添加“active”类 entry.target.classList.add("active"); - } - // Remove 'active' class otherwise - else { + } else { + // 否则移除“active”类 entry.target.classList.remove("active"); } }); }); -// Declares what to observe, and observes its properties. +// 声明观察的内容，并观察其属性。 const boxElList = document.querySelectorAll(".box"); boxElList.forEach((el) => { io.observe(el); @@ -57,6 +62,6 @@ boxElList.forEach((el) => { {{Compat}} -## 参考 +## 参见 - {{domxref("IntersectionObserver.unobserve()")}}