CKTIS / JavaScript
IntersectionObserver: observar interseções de elementos
IntersectionObserver comunica de forma assíncrona a interseção geométrica entre um elemento e uma região de referência. Conheça as opções root, rootMargin e threshold e distinga interseção de visibilidade real.
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
new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: 0 })IntersectionObserver é uma API Web do navegador, não uma funcionalidade ECMAScript. A disponibilidade no Node 24 não comprova o suporte no navegador; verifique o ambiente de destino.
root define a região de referência; o valor predefinido null representa a área de visualização. rootMargin aumenta ou reduz os limites através de 1–4 valores em píxeis ou percentagens. Estes deslocamentos só se aplicam a elementos-alvo do mesmo domínio de origem (same-origin-domain) e são ignorados para os de um domínio de origem diferente (cross-origin-domain). threshold aceita um número ou um array no intervalo [0, 1], sendo 0 o valor predefinido. A propriedade só de leitura thresholds expõe os rácios da área do elemento, ordenados.
Após o início da observação, a função de callback recebe normalmente uma entrada inicial para o elemento-alvo, mas a entrega não é garantida. A observação pode terminar antes de a entrada ser gerada, e takeRecords() pode retirá-la da fila antes de ser entregue à função de callback. As entradas seguintes são colocadas na fila quando se atravessa um limiar ou quando isIntersecting muda. A interseção geométrica não comprova visibilidade real; o contacto entre as arestas pode resultar em isIntersecting === true com uma área de interseção igual a zero.
observe(target) inicia a observação, unobserve(target) termina-a para um elemento e disconnect() termina-a para todos. O exemplo verifica a interseção completa inicial e limpa os recursos.
Exemplos
(() => {
if (!("IntersectionObserver" in window)) {
throw new Error("IntersectionObserver unavailable");
}
const root = document.createElement("div");
root.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;overflow:hidden;padding:0;border:0;";
const target = document.createElement("div");
target.style.cssText = "width:20px;height:20px;margin:0;";
root.append(target);
document.body.append(root);
const observer = new IntersectionObserver((entries) => {
console.log(entries[0].intersectionRatio === 1);
observer.disconnect();
root.remove();
}, { root, rootMargin: "0px", threshold: [0, 1] });
observer.observe(target);
})();Resultado
true
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.