Intersection Observer API 提供异步方式观测改变当交集目标元素与祖先元素或顶层文档的 viewport .
Historically, detecting visibility of an element, or the relative visibility of two elements in relation to each other, has been a difficult task for which solutions have been unreliable and prone to causing the browser and the sites the user is accessing to become sluggish. As the web has matured, the need for this kind of information has grown. Intersection information is needed for many reasons, such as:
Implementing intersection detection in the past involved event handlers and loops calling methods like
Element.getBoundingClientRect()
to build up the needed information for every element affected. Since all this code runs on the main thread, even one of these can cause performance problems. When a site is loaded with these tests, things can get downright ugly.
Consider a web page that uses infinite scrolling. It uses a vendor-provided library to manage the advertisements placed periodically throughout the page, has animated graphics here and there, and uses a custom library that draws notification boxes and the like. Each of these has its own intersection detection routines, all running on the main thread. The author of the web site may not even realize this is happening, since they may know very little about the inner workings of the two libraries they are using. As the user scrolls the page, these intersection detection routines are firing constantly during the scroll handling code, resulting in an experience that leaves the user frustrated with the browser, the web site, and their computer.
The Intersection Observer API lets code register a callback function that is executed whenever an element they wish to monitor enters or exits another element (or the viewport ), or when the amount by which the two intersect changes by a requested amount. This way, sites no longer need to do anything on the main thread to watch for this kind of element intersection, and the browser is free to optimize the management of intersections as it sees fit.
One thing the Intersection Observer API can't tell you: the exact number of pixels that overlap or specifically which ones they are; however, it covers the much more common use case of "If they intersect by somewhere around N %, I need to do something."
The Intersection Observer API allows you to configure a callback that is called when either of these circumstances occur:
Typically, you'll want to watch for intersection changes with regard to the element's closest scrollable ancestor, or, if the element isn't a descendant of a scrollable element, the viewport. To watch for intersection relative to the root element, specify
null
.
Whether you're using the viewport or some other element as the root, the API works the same way, executing a callback function you provide whenever the visibility of the target element changes so that it crosses desired amounts of intersection with the root.
The degree of intersection between the target element and its root is the intersection ratio . This is a representation of the percentage of the target element which is visible as a value between 0.0 and 1.0.
Create the intersection observer by calling its constructor and passing it a callback function to be run whenever a threshold is crossed in one direction or the other:
let options = {
root: document.querySelector('#scrollArea'),
rootMargin: '0px',
threshold: 1.0
}
let observer = new IntersectionObserver(callback, options);
A threshold of 1.0 means that when 100% of the target is visible within the element specified by the
root
option, the callback is invoked.
选项
object passed into the
IntersectionObserver()
constructor let you control the circumstances under which the observer's callback is invoked. It has the following fields:
root
null
.
rootMargin
margin
property, e.g. "
10px 20px 30px 40px"
(top, right, bottom, left). The values can be percentages. This set of values serves to grow or shrink each side of the root element's bounding box before computing intersections. Defaults to all zeros.
threshold
Either a single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. If you only want to detect when visibility passes the 50% mark, you can use a value of 0.5. If you want the callback to run every time visibility passes another 25%, you would specify the array [0, 0.25, 0.5, 0.75, 1]. The default is 0 (meaning as soon as even one pixel is visible, the callback will be run). A value of 1.0 means that the threshold isn't considered passed until every pixel is visible.
Once you have created the observer, you need to give it a target element to watch:
let target = document.querySelector('#listItem');
observer.observe(target);
// the callback we setup for the observer will be executed now for the first time
// it waits until we assign a target to our observer (even if the target is currently not visible)
Whenever the target meets a threshold specified for the
IntersectionObserver
, the callback is invoked. The callback receives a list of
IntersectionObserverEntry
objects and the observer:
let callback = (entries, observer) => {
entries.forEach(entry => {
// Each entry describes an intersection change for one observed
// target element:
// entry.boundingClientRect
// entry.intersectionRatio
// entry.intersectionRect
// entry.isIntersecting
// entry.rootBounds
// entry.target
// entry.time
});
};
The list of entries received by the callback includes one entry for each target which reporting a change in its intersection status. Check the value of the
isIntersecting
property to see if the entry represents an element that currently intersects with the root.
Be aware that your callback is executed on the main thread. It should operate as quickly as possible; if anything time-consuming needs to be done, use
Window.requestIdleCallback()
.
Also, note that if you specified the
root
option, the target must be a descendant of the root element.
All areas considered by the Intersection Observer API are rectangles; elements which are irregularly shaped are considered as occupying the smallest rectangle which encloses all of the element's parts. Similarly, if the visible portion of an element is not rectangular, the element's intersection rectangle is construed to be the smallest rectangle that contains all the visible portions of the element.
It's useful to understand a bit about how the various properties provided by
IntersectionObserverEntry
describe an intersection.
Before we can track the intersection of an element with a container, we need to know what that container is. That container is the
intersection root
，或
root element
. This can be either a specific element in the document which is an ancestor of the element to be observed, or
null
to use the document's viewport as the container.
root intersection rectangle is the rectangle used to check against the target or targets. This rectangle is determined like this:
Document
), the root intersection rectangle is the viewport's rectangle.
getBoundingClientRect()
on it).
The root intersection rectangle can be adjusted further by setting the
root margin
,
rootMargin
, when creating the
IntersectionObserver
. The values in
rootMargin
define offsets added to each side of the intersection root's bounding box to create the final intersection root bounds (which are disclosed in
IntersectionObserverEntry.rootBounds
when the callback is executed).
Rather than reporting every infinitesimal change in how much a target element is visible, the Intersection Observer API uses thresholds . When you create an observer, you can provide one or more numeric values representing percentages of the target element which are visible. Then, the API only reports changes to visibility which cross these thresholds.
For example, if you want to be informed every time a target's visibility passes backward or forward through each 25% mark, you would specify the array [0, 0.25, 0.5, 0.75, 1] as the list of thresholds when creating the observer.
When the callback is invoked, it receives a list of
IntersectionObserverEntry
objects, one for each observed target which has had the degree to which it intersects the root change such that the amount exposed crosses over one of the thresholds, in either direction.
You can see if the target
currently
intersects the root by looking at the entry's
isIntersecting
property; if its value is
true
, the target is at least partially intersecting the root element or document. This lets you determine whether the entry represents a transition from the elements intersecting to no longer intersecting or a transition from not intersecting to intersecting.
Note that it's possible to have a non-zero intersection rectangle, which can happen if the intersection is exactly along the boundary between the two or the area of
boundingClientRect
is zero. This state of the target and root sharing a boundary line is not considered enough to be considered transitioning into an intersecting state.
To get a feeling for how thresholds work, try scrolling the box below around. Each colored box within it displays the percentage of itself that's visible in all four of its corners, so you can see these ratios change over time as you scroll the container. Each box has a different set of thresholds:
IntersectionObserver.thresholds
array is
[0.00, 0.01, 0.02, ..., 0.99, 1.00]
.
<template id="boxTemplate">
<div class="sampleBox">
<div class="label topLeft"></div>
<div class="label topRight"></div>
<div class="label bottomLeft"></div>
<div class="label bottomRight"></div>
</div>
</template>
<main>
<div class="contents">
<div class="wrapper">
</div>
</div>
</main>
.contents {
position: absolute;
width: 700px;
height: 1725px;
}
.wrapper {
position: relative;
top: 600px;
}
.sampleBox {
position: relative;
left: 175px;
width: 150px;
background-color: rgb(245, 170, 140);
border: 2px solid rgb(201, 126, 17);
padding: 4px;
margin-bottom: 6px;
}
#box1 {
height: 200px;
}
#box2 {
height: 75px;
}
#box3 {
height: 150px;
}
#box4 {
height: 100px;
}
.label {
font: 14px "Open Sans", "Arial", sans-serif;
position: absolute;
margin: 0;
background-color: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(0, 0, 0, 0.7);
width: 3em;
height: 18px;
padding: 2px;
text-align: center;
}
.topLeft {
left: 2px;
top: 2px;
}
.topRight {
right: 2px;
top: 2px;
}
.bottomLeft {
bottom: 2px;
left: 2px;
}
.bottomRight {
bottom: 2px;
right: 2px;
}
let observers = [];
startup = () => {
let wrapper = document.querySelector(".wrapper");
// Options for the observers
let observerOptions = {
root: null,
rootMargin: "0px",
threshold: []
};
// An array of threshold sets for each of the boxes. The
// first box's thresholds are set programmatically
// since there will be so many of them (for each percentage
// point).
let thresholdSets = [
[],
[0.5],
[0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0],
[0, 0.25, 0.5, 0.75, 1.0]
];
for (let i=0; i<=1.0; i+= 0.01) {
thresholdSets[0].push(i);
}
// Add each box, creating a new observer for each
for (let i=0; i<4; i++) {
let template = document.querySelector("#boxTemplate").content.cloneNode(true);
let boxID = "box" + (i+1);
template.querySelector(".sampleBox").id = boxID;
wrapper.appendChild(document.importNode(template, true));
// Set up the observer for this box
observerOptions.threshold = thresholdSets[i];
observers[i] = new IntersectionObserver(intersectionCallback, observerOptions);
observers[i].observe(document.querySelector("#" + boxID));
}
// Scroll to the starting position
document.scrollingElement.scrollTop = wrapper.firstElementChild.getBoundingClientRect().top + window.scrollY;
document.scrollingElement.scrollLeft = 750;
}
intersectionCallback = (entries) => {
entries.forEach((entry) => {
let box = entry.target;
let visiblePct = (Math.floor(entry.intersectionRatio * 100)) + "%";
box.querySelector(".topLeft").innerHTML = visiblePct;
box.querySelector(".topRight").innerHTML = visiblePct;
box.querySelector(".bottomLeft").innerHTML = visiblePct;
box.querySelector(".bottomRight").innerHTML = visiblePct;
});
}
startup();
The browser computes the final intersection rectangle as follows; this is all done for you, but it can be helpful to understand these steps in order to better grasp exactly when intersections will occur.
getBoundingClientRect()
on the target. This is the largest the intersection rectangle may be. The remaining steps will remove any portions that don't intersect.
overflow
property. Setting
overflow
to anything but
visible
causes clipping to occur.
<iframe>
, the intersection rectangle is clipped to the containing context's viewport, and recursion upward through the containers continues with the container's containing block. So if the top level of an
<iframe>
is reached, the intersection rectangle is clipped to the frame's viewport, then the frame's parent element is the next block recursed through toward the intersection root.
document
.
When the amount of a target element which is visible within the root element crosses one of the visibility thresholds, the
IntersectionObserver
object's callback is executed. The callback receives as input an array of all of
IntersectionObserverEntry
objects, one for each threshold which was crossed, and a reference to the
IntersectionObserver
对象自身。
Each entry in the list of thresholds is an
IntersectionObserverEntry
object describing one threshold that was crossed; that is, each entry describes how much of a given element is intersecting with the root element, whether or not the element is considered to be intersecting or not, and the direction in which the transition occurred.
The code snippet below shows a callback which keeps a counter of how many times elements transition from not intersecting the root to intersecting by at least 75%. For a threshold value of 0.0 (default) the callback is called
approximately
upon transition of the boolean value of
isIntersecting
. The snippet thus first checks that the transition is a positive one, then determines whether
intersectionRatio
is above 75%, in which case it increments the counter.
intersectionCallback(entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
let elem = entry.target;
if (entry.intersectionRatio >= 0.75) {
intersectionCounter++;
}
}
});
}
IntersectionObserver
Document
's
viewport
. The ancestor or viewport is referred to as the
root
.
IntersectionObserverEntry
IntersectionObserver
callback, or by calling
IntersectionObserver.takeRecords()
.
This simple example causes a target element to change its color and transparency as it becomes more or less visible. At Timing element visibility with the Intersection Observer API , you can find a more extensive example showing how to time how long a set of elements (such as ads) are visible to the user and to react to that information by recording statistics or by updating elements..
The HTML for this example is very short, with a primary element which is the box that we'll be targeting (with the creative ID
"box"
) and some contents within the box.
<div id="box">
<div class="vertical">
Welcome to <strong>The Box!</strong>
</div>
</div>
The CSS isn't terribly important for the purposes of this example; it lays out the element and establishes that the
background-color
and
border
attributes can participate in
CSS 过渡
, which we'll use to affect the changes to the element as it becomes more or less obscured.
#box {
background-color: rgba(40, 40, 190, 255);
border: 4px solid rgb(20, 20, 120);
transition: background-color 1s, border 1s;
width: 350px;
height: 350px;
display: flex;
align-items: center;
justify-content: center;
padding: 20px;
}
.vertical {
color: white;
font: 32px "Arial";
}
.extra {
width: 350px;
height: 350px;
margin-top: 10px;
border: 4px solid rgb(20, 20, 120);
text-align: center;
padding: 20px;
}
Finally, let's take a look at the JavaScript code that uses the Intersection Observer API to make things happen.
First, we need to prepare some variables and install the observer.
const numSteps = 20.0;
let boxElement;
let prevRatio = 0.0;
let increasingColor = "rgba(40, 40, 190, ratio)";
let decreasingColor = "rgba(190, 40, 40, ratio)";
// Set things up
window.addEventListener("load", (event) => {
boxElement = document.querySelector("#box");
createObserver();
}, false);
The constants and variables we set up here are:
numSteps
A constant which indicates how many thresholds we want to have between a visibility ratio of 0.0 and 1.0.
prevRatio
This variable will be used to record what the visibility ratio was the last time a threshold was crossed; this will let us figure out whether the target element is becoming more or less visible.
increasingColor
A string defining a color we'll apply to the target element when the visibility ratio is increasing. The word "ratio" in this string will be replaced with the target's current visibility ratio, so that the element not only changes color but also becomes increasingly opaque as it becomes less obscured.
decreasingColor
Similarly, this is a string defining a color we'll apply when the visibility ratio is decreasing.
调用
Window.addEventListener()
to start listening for the
load
event; once the page has finished loading, we get a reference to the element with the ID
"box"
使用
querySelector()
, then call the
createObserver()
method we'll create in a moment to handle building and installing the intersection observer.
createObserver()
method is called once page load is complete to handle actually creating the new
IntersectionObserver
and starting the process of observing the target element.
function createObserver() {
let observer;
let options = {
root: null,
rootMargin: "0px",
threshold: buildThresholdList()
};
observer = new IntersectionObserver(handleIntersect, options);
observer.observe(boxElement);
}
This begins by setting up an
选项
object containing the settings for the observer. We want to watch for changes in visibility of the target element relative to the document's viewport, so
root
is
null
. We need no margin, so the margin offset,
rootMargin
, is specified as "0px". This causes the observer to watch for changes in the intersection between the target element's bounds and those of the viewport, without any added (or subtracted) space.
The list of visibility ratio thresholds,
threshold
, is constructed by the function
buildThresholdList()
. The threshold list is built programmatically in this example since there are a number of them and the number is intended to be adjustable.
一旦
选项
is ready, we create the new observer, calling the
IntersectionObserver()
constructor, specifying a function to be called when intersection crosses one of our thresholds,
handleIntersect()
, and our set of options. We then call
observe()
on the returned observer, passing into it the desired target element.
We could opt to monitor multiple elements for visibility intersection changes with respect to the viewport by calling
observer.observe()
for each of those elements, if we wanted to do so.
buildThresholdList()
function, which builds the list of thresholds, looks like this:
function buildThresholdList() {
let thresholds = [];
let numSteps = 20;
for (let i=1.0; i<=numSteps; i++) {
let ratio = i/numSteps;
thresholds.push(ratio);
}
thresholds.push(0);
return thresholds;
}
This builds the array of thresholds—each of which is a ratio between 0.0 and 1.0, by pushing the value
i/numSteps
onto the
thresholds
array for each integer
i
between 1 and
numSteps
. It also pushes 0 to include that value. The result, given the default value of
numSteps
(20), is the following list of thresholds:
| # | Ratio | # | Ratio |
|---|---|---|---|
| 1 | 0.05 | 11 | 0.55 |
| 2 | 0.1 | 12 | 0.6 |
| 3 | 0.15 | 13 | 0.65 |
| 4 | 0.2 | 14 | 0.7 |
| 5 | 0.25 | 15 | 0.75 |
| 6 | 0.3 | 16 | 0.8 |
| 7 | 0.35 | 17 | 0.85 |
| 8 | 0.4 | 18 | 0.9 |
| 9 | 0.45 | 19 | 0.95 |
| 10 | 0.5 | 20 | 1.0 |
We could, of course, hard-code the array of thresholds into our code, and often that's what you'll end up doing. But this example leaves room for adding configuration controls to adjust the granularity, for example.
When the browser detects that the target element (in our case, the one with the ID
"box"
) has been unveiled or obscured such that its visibility ratio crosses one of the thresholds in our list, it calls our handler function,
handleIntersect()
:
function handleIntersect(entries, observer) {
entries.forEach((entry) => {
if (entry.intersectionRatio > prevRatio) {
entry.target.style.backgroundColor = increasingColor.replace("ratio", entry.intersectionRatio);
} else {
entry.target.style.backgroundColor = decreasingColor.replace("ratio", entry.intersectionRatio);
}
prevRatio = entry.intersectionRatio;
});
}
For each
IntersectionObserverEntry
in the list
entries
, we look to see if the entry's
intersectionRatio
is going up; if it is, we set the target's
background-color
to the string in
increasingColor
(remember, it's
"rgba(40, 40, 190, ratio)"
), replaces the word "ratio" with the entry's
intersectionRatio
. The result: not only does the color get changed, but the transparency of the target element changes, too; as the intersection ratio goes down, the background color's alpha value goes down with it, resulting in an element that's more transparent.
Similarly, if the
intersectionRatio
is going down, we use the string
decreasingColor
and replace the word "ratio" in that with the
intersectionRatio
before setting the target element's
background-color
.
Finally, in order to track whether the intersection ratio is going up or down, we remember the current ratio in the variable
prevRatio
.
Below is the resulting content. Scroll this page up and down and notice how the appearance of the box changes as you do so.
There's an even more extensive example at Timing element visibility with the Intersection Observer API .
| 规范 | 状态 | 注释 |
|---|---|---|
| Intersection Observer | 工作草案 |
| 桌面 | 移动 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
IntersectionObserver
|
Chrome 51 | Edge 15 |
Firefox
55
|
IE No | Opera 38 | Safari 12.1 | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android 41 | Safari iOS 12.2 | Samsung Internet Android 5.0 |
IntersectionObserver()
构造函数
|
Chrome 51 | Edge 15 |
Firefox
55
|
IE No | Opera 38 | Safari 12.1 | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS 12.2 | Samsung Internet Android 5.0 |
disconnect
|
Chrome 51 |
Edge
15
|
Firefox
55
|
IE No | Opera Yes | Safari ? | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS ? | Samsung Internet Android 5.0 |
observe
|
Chrome 51 | Edge 15 |
Firefox
55
|
IE No | Opera Yes | Safari 12.1 | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS 12.2 | Samsung Internet Android 5.0 |
root
|
Chrome 51 | Edge 15 |
Firefox
55
|
IE No | Opera Yes | Safari 12.1 | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS 12.2 | Samsung Internet Android 5.0 |
rootMargin
|
Chrome 51 | Edge 15 |
Firefox
55
|
IE No | Opera Yes |
Safari
12.1
|
WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? |
Safari iOS
12.2
|
Samsung Internet Android 5.0 |
takeRecords
|
Chrome 51 |
Edge
15
|
Firefox
55
|
IE No | Opera Yes | Safari ? | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS ? | Samsung Internet Android 5.0 |
thresholds
|
Chrome 51 | Edge 15 |
Firefox
55
|
IE No | Opera Yes | Safari 12.1 | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS 12.2 | Samsung Internet Android 5.0 |
unobserve
|
Chrome 51 |
Edge
15
|
Firefox
55
|
IE No | Opera Yes | Safari 12.1 | WebView Android 51 | Chrome Android 51 | Firefox Android ? | Opera Android ? | Safari iOS 12.2 | Samsung Internet Android 5.0 |
完整支持
不支持
兼容性未知
实验。期望将来行为有所改变。
见实现注意事项。
用户必须明确启用此特征。
IntersectionObserver
and
IntersectionObserverEntry