Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

IntersectionObserverEntry — ler a intersecção de um elemento

IntersectionObserverEntry descreve a intersecção de um elemento observado com a respetiva raiz num instante registado. As propriedades isIntersecting, target e intersectionRatio permitem identificar o estado da intersecção, o elemento e a fração da sua área que está em intersecção.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

entry.isIntersecting
entry.target
entry.intersectionRatio

IntersectionObserverEntry é uma captura instantânea da geometria, não um objeto atualizado continuamente. O navegador entrega as entradas de forma assíncrona a uma função de retorno de IntersectionObserver; também é possível obter as entradas pendentes através de takeRecords(). A função de retorno deve processar todo o array entries, e não apenas a primeira entrada.

IntersectionObserverEntry.target referencia o Element observado. IntersectionObserverEntry.isIntersecting é um booleano que indica se existe intersecção com a raiz. IntersectionObserverEntry.intersectionRatio é um número entre 0 e 1: a área de intersectionRect dividida pela área de boundingClientRect. Para um alvo com área zero, o valor é 1 quando isIntersecting é true e 0 caso contrário; não consideres estas duas propriedades equivalentes.

A primeira notificação descreve o estado inicial após observe(). As notificações seguintes dependem, entre outros fatores, de se cruzarem os valores threshold configurados; não constituem um relatório de cada píxel percorrido ao deslocar a página. Para reagir quando metade da área está em intersecção, inclui o limiar 0.5 e verifica entry.isIntersecting && entry.intersectionRatio >= 0.5. A observação geométrica normal não prova que outro elemento não esteja a cobrir o alvo.

Esta é uma API Web do navegador, não uma funcionalidade de uma edição específica do ECMAScript. A MDN indica que a interface principal está amplamente disponível desde março de 2019; as funcionalidades adicionais podem ter um suporte diferente. A presença de Node 24 num repositório não comprova a disponibilidade da API. O exemplo coloca um alvo com 100px de altura dentro de uma raiz de recorte com 50px de altura e, em seguida, termina a observação.

Exemplos

(() => {
  const root = document.createElement('div');
  root.style.cssText = 'all:initial;position:fixed;top:0;left:0;width:100px;height:50px;overflow:hidden;';
  const target = document.createElement('div');
  target.style.cssText = 'all:initial;display:block;width:100px;height:100px;';
  root.append(target);
  document.body.append(root);

  const observer = new IntersectionObserver((entries) => {
    for (const entry of entries) {
      console.log(
        entry.isIntersecting,
        entry.target === target,
        entry.intersectionRatio.toFixed(2)
      );
    }
    observer.disconnect();
    root.remove();
  }, { root, threshold: [0, 0.5, 1] });

  observer.observe(target);
})();

Resultado

true true 0.50

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes