Intersection Observer API дозволяє веб-застосункам асинхронно стежити за зміною перетину елемента з його батьком чи областю видимості документа {{Glossary("viewport")}}.

Історично склалося так, що виявлення видимості окремого елемента чи видимості двох елементів по відношенню один до одного було непростою задачею. Варіанти вирішення цієї задачі були ненадійними і сповільнювали роботу браузера. На жаль, з "дорослішанням" вебу, необхідність у вирішенні цієї проблеми тільки зростала, з різних причин, таких як:

Раніше реалізація виявлення пересічення елементів означала використання обробників подій і циклів, викликаючих методи типу {{domxref("Element.getBoundingClientRect()")}}, щоб зібрати необхідну інформацію про кожен зачеплений елемент. Оскільки весь цей код працює в основному потоці, виникають проблеми з продуктивністю.

Розглянемо веб-сторінку з безкінечним скролом. На сторінці використовується бібліотека для керування періодично розміщуваною по всій сторінці рекламою, всюди анімована графіка, а також бібліотека для відображення спливаючих вікон. І всі ці речі використовують свої власні правила для визначення перетинів, і всі вони запущені в основному потоці. Автор сайту може навіть не підозрювати про цю проблему, а також може не знати, як працюють сторонні бібліотеки зсередини. В той же час користувач по ходу прокрутки сторінки стикається з тим, що робота сайта сповільнюється постійним спрацьовуванням виявлення перетинів, що в підсумку призводить до того, що користувач не задоволений браузером, сайтом і своїм комп'ютером.

Intersection Observer API дає можливість зареєструвати callback-функцію, яка виконається при перетині спостережуваним елементом кордонів іншого елемента (чи області видимості документа {{Glossary("viewport")}}), або при зміні величини перетину на визначене значення. Таким чином, більше немає необхідності вираховувати перетин елементів в основному потоці, і браузер може оптимізовувати ці процеси на свій погляд.

Observer API не дозволить дізнатися точне число пікселів чи визначати конкретні пікселі в перетині; проте, його використання покриває найбільш поширені випадки, наприклад "Якщо елементи перетинаються на N%, зроби це і це".

Основні поняття і використання Intersection Observer API

Intersection Observer API дозволяє вказати функцію, яка буде викликана щоразу для елемента (target) при перетині його з областю видимості документа (по-замовчуванню) чи заданим елементом (root).

Зазвичай, використовується відстеження перетину елементу з областю видимості (необхідно вказати null в якості кореневого елементу).

Чи використовуємо ми область видимості чи інший елемент в якості кореневого, API працює однаково, викликаючи задану вами функцію зворотнього виклику, щоразу, коли видимість цільового елементу змінюється так, що вона перетинає в потрібному ступені кореневий елемент.

Ступінь перетину цільового і кореневого елементу задається в діапазоні від 0.0 до 1.0, де 1.0 це повний перетин цільовим елементом кордонів кореневого.

Створення intersection observer

Для початку з допомогою конструктору потрібно створити об'єкт-спостерігач, вказати для нього функцію для виклику і налаштування відстеження:

Параметр threshold зі значенням 1.0 означає що функція буде викликана при 100% перетину об'єкта (за яким ми стежимо) з об'єктом root.

Налаштування Intersection observer

The options object passed into the {{domxref("IntersectionObserver.IntersectionObserver", "IntersectionObserver()")}} constructor let you control the circumstances under which the observer's callback is invoked. It has the following fields:

Цільовий елемент, який буде спостерігатися

Після того, як ви створили спостерігача, вам потрібно дати йому цільовий елемент для перегляду:

Щоразу, коли ціль досягає порогового значення, вказаного для IntersectionObserver, викликається функція зворотнього виклику callback. Де callback отримує список об'єктів IntersectionObserverEntry і спостерігача:

Зверніть увагу, що функція зворотнього виклику запускається в головному потоці і повинна виконуватися якнайшвидше, тому якщо щось забирає багато часу, то використовуйте {{domxref("Window.requestIdleCallback()")}}.

Також зверніть увагу, що якщо ви вказали опцію root, цільовий елемент повинен бути потомком кореневого елементу.

How intersection is calculated

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 {{domxref("IntersectionObserverEntry")}} describe an intersection.

The intersection root and root margin

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, or 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.

The root intersection rectangle is the rectangle used to check against the target or targets. This rectangle is determined like this:

The root intersection rectangle can be adjusted further by setting the root margin, rootMargin, when creating the {{domxref("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 {{domxref("IntersectionObserverEntry.rootBounds")}} when the callback is executed).

Thresholds

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. You can tell which direction the visibility changed in (that is, whether the element became more visible or less visible) by checking the value of the {{domxref("IntersectionObserverEntry.isIntersecting", "isIntersecting")}} property on the {{domxref("IntersectionObserverEntry")}} passed into the callback function at the time of the visibility change. If isIntersecting is true, the target element has become at least as visible as the threshold that was passed. If it's false, the target is no longer as visible as the given threshold.

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:

Threshold example

<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();

Clipping and the intersection rectangle

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.

Intersection change callbacks

When the amount of a target element which is visible within the root element crosses one of the visibility thresholds, the {{domxref("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 object itself.

Each entry in the list of thresholds is an {{domxref("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%.

Інтерфейси

A simple example

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..

HTML

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.

CSS

The CSS isn't terribly important for the purposes of this example; it lays out the element and establishes that the {{cssxref("background-color")}} and {{cssxref("border")}} attributes can participate in CSS transitions, which we'll use to affect the changes to the element as it becomes more or less obscured.

JavaScript

Finally, let's take a look at the JavaScript code that uses the Intersection Observer API to make things happen.

Setting up

We call {{domxref("EventTarget.addEventListener", "Window.addEventListener()")}} to start listening for the {{event("load")}} event; once the page has finished loading, we get a reference to the element with the ID "box" using {{domxref("Document.querySelector", "querySelector()")}}, then call the createObserver() method we'll create in a moment to handle building and installing the intersection observer.

Creating the intersection observer

The createObserver() method is called once page load is complete to handle actually creating the new {{domxref("IntersectionObserver")}} and starting the process of observing the target element.

This begins by setting up an options 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.

Once options is ready, we create the new observer, calling the {{domxref("IntersectionObserver.IntersectionObserver", "IntersectionObserver()")}} constructor, specifying a function to be called when intersection crosses one of our thresholds, handleIntersect(), and our set of options. We then call {{domxref("IntersectionObserver.observe", "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.

Building the array of threshold ratios

The buildThresholdList() function, which builds the list of thresholds, looks like this:

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:

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.

Handling intersection changes

#	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

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():

For each {{domxref("IntersectionObserverEntry")}} in the list entries, we look to see if the entry's {{domxref("IntersectionObserverEntry.intersectionRatio", "intersectionRatio")}} is going up; if it is, we set the target's {{cssxref("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.

Result

Below is the resulting content. Scroll this page up and down and notice how the appearance of the box changes as you do so.

Основні поняття і використання Intersection Observer API