CKTIS / JavaScript
Opções de IntersectionObserver: root, rootMargin e threshold
`root` escolhe a área de referência, `rootMargin` ajusta os seus limites para o cálculo e `threshold` define as frações da área do alvo que desencadeiam notificações.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: [0, 0.5, 1] })IntersectionObserver é uma API do navegador, não uma funcionalidade de ECMAScript. root escolhe a área de referência: se for omitida ou se receber null, usa-se a área visível do documento de nível superior. A raiz explícita pode ser um Document ou um Element, por exemplo um contentor com deslocamento. Se a raiz for um elemento, o alvo tem de ser seu descendente na cadeia de blocos contentores da disposição da página.
rootMarginé uma cadeia de um a quatro valores, expressos como comprimentos absolutos de CSS ou percentagens, distribuídos como emmargindo CSS: cima, direita, baixo, esquerda. Segundo a especificação, os comprimentos absolutos, como os expressos emcm, são convertidos em píxeis ao analisar a cadeia. Para garantir a compatibilidade entre navegadores, usapxou%, pois alguns navegadores rejeitam outras unidades absolutas. O valor predefinido de cada lado é0px. As percentagens referem-se à largura do retângulo original da raiz, mesmo em cima e em baixo. Valores positivos ampliam o retângulo usado no cálculo; os negativos reduzem-no. Isto não altera a disposição nem anula o recorte por antecessores intermédios. Para alvos de outra origem, a margem é ignorada eentry.rootBoundsénull.
thresholdaceita um número ou um array de números entre0e1, inclusive. Omitir a opção ou passar um array vazio dá um limiar de0. A opção do construtor chama-sethreshold; a propriedade só de leituraobserver.thresholdsdevolve um array ordenado numericamente por ordem crescente. Um limiar fora do intervalo lança umRangeError; umrootMargininválido lança umaDOMExceptioncom o nomeSyntaxError.
Após
observe(target), a função de retorno recebe assincronamente uma entrada inicial, mesmo sem interseção. São colocadas mais entradas em fila quando se atravessa um limiar em qualquer sentido ou quandoentry.isIntersectingmuda, e não a cada alteração da proporção.0.5significa metade da área do retângulo delimitador do alvo, não da raiz. O contacto entre bordos pode darisIntersecting: truecomintersectionRatio: 0. Se o retângulo do alvo tiver área nula, a proporção é1seisIntersectingfor verdadeiro e0caso contrário. Uma interseção geométrica não prova que o utilizador veja o alvo.
As opções ficam fixas ao criar o observador. Para as alterar, cria um novo observador. Usa
unobserve(target)para deixar de observar um alvo oudisconnect()para deixar de observar todos. Confirma se o ambiente de execução suporta a API.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IntersectionObserver options</title>
</head>
<body>
<script>
{
const root = document.createElement("div");
const spacer = document.createElement("div");
const target = document.createElement("div");
root.style.cssText = "width: 120px; height: 100px; overflow: hidden";
spacer.style.height = "120px";
target.style.cssText = "height: 40px; background: teal";
root.append(spacer, target);
document.body.append(root);
const observer = new IntersectionObserver(([entry], observer) => {
console.log(`root matches: ${observer.root === root}`);
console.log(`rootMargin: ${observer.rootMargin}`);
console.log(`thresholds: ${JSON.stringify(observer.thresholds)}`);
console.log(`isIntersecting: ${entry.isIntersecting}`);
console.log(`intersectionRatio: ${entry.intersectionRatio}`);
observer.disconnect();
root.remove();
}, {
root,
rootMargin: "0px 0px 40px",
threshold: [1, 0, 0.5],
});
observer.observe(target);
}
</script>
</body>
</html>Resultado
root matches: true rootMargin: 0px 0px 40px 0px thresholds: [0,0.5,1] isIntersecting: true intersectionRatio: 0.5
Guarda o exemplo como ficheiro HTML, abre-o num separador ativo do navegador e consulta o resultado na consola de desenvolvimento. O alvo começa 20 px abaixo do bordo inferior da raiz. A margem inferior de 40 px inclui metade da altura do alvo em toda a sua largura. A primeira entrada indica, por isso, `intersectionRatio: 0.5`. O código desliga o observador e remove os elementos de demonstração.
Lições relacionadas
- JavaScript · Lição 30 · Intermédio · Versão: 3
Fontes
- IntersectionObserver: IntersectionObserver() constructor
- Intersection Observer API
- IntersectionObserver: rootMargin property
- Intersection Observer specification — Parse a margin
- IntersectionObserver: thresholds property
- IntersectionObserver: observe() method
- IntersectionObserverEntry: intersectionRatio property
- IntersectionObserverEntry: isIntersecting property
- IntersectionObserver: disconnect() method
- HTML Standard — Update the rendering