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

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 em margin do CSS: cima, direita, baixo, esquerda. Segundo a especificação, os comprimentos absolutos, como os expressos em cm, são convertidos em píxeis ao analisar a cadeia. Para garantir a compatibilidade entre navegadores, usa px ou %, 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 e entry.rootBounds é null.

threshold aceita um número ou um array de números entre 0 e 1, inclusive. Omitir a opção ou passar um array vazio dá um limiar de 0. A opção do construtor chama-se threshold; a propriedade só de leitura observer.thresholds devolve um array ordenado numericamente por ordem crescente. Um limiar fora do intervalo lança um RangeError; um rootMargin inválido lança uma DOMException com o nome SyntaxError.

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 quando entry.isIntersecting muda, e não a cada alteração da proporção. 0.5 significa metade da área do retângulo delimitador do alvo, não da raiz. O contacto entre bordos pode dar isIntersecting: true com intersectionRatio: 0. Se o retângulo do alvo tiver área nula, a proporção é 1 se isIntersecting for verdadeiro e 0 caso 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 ou disconnect() 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