CKTIS / JavaScript
IntersectionObserverEntry: isIntersecting, intersectionRatio e target
Consulta o estado de interseção, a fração da área em interseção e o elemento observado. Distingue o estado de interseção da passagem por um limiar.
Versão: Current web platform; runtime support varies
Sintaxe
entry.isIntersecting // boolean
entry.intersectionRatio // number in [0, 1]
entry.target // ElementUm IntersectionObserverEntry regista o estado de um alvo no momento da medição. A função de callback do observador recebe as entradas de forma assíncrona e pode receber várias de uma vez. entry.target é o mesmo Element passado a observe(), não root. As três propriedades são só de leitura, mas o próprio elemento pode ser alterado. Esta API pertence à plataforma Web, não ao ECMAScript 2024.
entry.isIntersecting é um booleano que indica se o alvo intersecta a zona de referência do observador no momento da medição. Com o valor predefinido root: null, essa zona é a área de visualização do documento de nível superior, e não a do iframe que contém o alvo. Ainda assim, a área de visualização do iframe pode limitar a interseção calculada. true descreve um estado, não necessariamente uma transição para esse estado. Segundo a especificação, o contacto entre arestas pode contar como interseção mesmo quando a área de interseção é nula.
entry.intersectionRatio é um número entre 0 e 1: a área de intersectionRect dividida pela área de boundingClientRect do alvo, não pela da zona de referência. Se o retângulo do alvo tiver área nula, o resultado é 1 quando isIntersecting é true e 0 caso contrário. A medição predefinida é geométrica e não prova que o alvo não esteja tapado por outro elemento.
Após observe(), recebes uma entrada inicial, mesmo que o alvo esteja fora da zona de referência. Podem surgir novas entradas quando se passa por um limiar em qualquer dos sentidos ou quando isIntersecting muda. Nem todas as alterações da proporção geram uma entrada. threshold: 0.5 define um limiar de notificação, enquanto entry.intersectionRatio >= 0.5 testa o valor de uma entrada específica.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IntersectionObserverEntry example</title>
</head>
<body>
<script>
(() => {
const root = document.createElement('div');
root.style.cssText = 'position:relative;overflow:hidden;width:100px;height:100px';
const target = document.createElement('div');
target.style.cssText = 'position:absolute;left:0;top:50px;width:100px;height:100px;background:royalblue';
root.append(target);
document.body.append(root);
let moved = false;
const observer = new IntersectionObserver((entries) => {
for (const entry of entries) {
console.log(`${entry.isIntersecting} ${entry.intersectionRatio} ${entry.target === target}`);
if (!moved) {
moved = true;
target.style.top = '150px';
} else {
observer.disconnect();
root.remove();
}
}
}, { root, threshold: 0.5 });
observer.observe(target);
})();
</script>
</body>
</html>Resultado
true 0.5 true false 0 true
Guarda o exemplo como ficheiro HTML e abre-o num separador próprio de um navegador que suporte a API. Abre a consola de desenvolvimento e recarrega a página. A primeira entrada mostra que metade da área do alvo intersecta a zona de referência. O código desloca o alvo totalmente para fora dessa zona e a segunda entrada indica que já não existe interseção. Ambas as entradas referem-se ao mesmo elemento. Após a segunda, o código termina a observação e remove a zona de referência.
Lições relacionadas
- JavaScript · Lição 37 · Avançado · Versão: 4
Fontes
- IntersectionObserverEntry: isIntersecting property
- IntersectionObserverEntry: intersectionRatio property
- IntersectionObserverEntry: target property
- IntersectionObserver: observe() method
- IntersectionObserver: IntersectionObserver() constructor
- HTML Standard — Web application APIs
- Intersection Observer specification — intersection geometry