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

CKTIS / JavaScript

ResizeObserverEntry: elemento observado e retângulo de conteúdo

Usa `target` para identificar o elemento a que a entrada diz respeito e `contentRect` para ler as dimensões comunicadas, sem espaçamento interior nem bordas num elemento HTML.

Versão: Current web platform; runtime support varies

Sintaxe

entry.target
entry.contentRect
entry.contentRect.width
entry.contentRect.height

Durante a renderização, o navegador passa um array de entradas ResizeObserverEntry à função de retorno de chamada de ResizeObserver. A propriedade entry.target é só de leitura e referencia o elemento observado, não uma cópia. Se observares vários elementos, compara target com uma referência conhecida usando ===.

entry.contentRect é um objeto DOMRectReadOnly que guarda a medição da notificação e não é atualizado em tempo real. Num elemento HTML, width e height são a largura e a altura físicas da caixa de conteúdo, em píxeis CSS, sem espaçamento interior nem bordas. Num elemento gráfico SVG sem uma caixa de disposição CSS, a medição descreve o seu retângulo delimitador. Não o confundas com getBoundingClientRect(), que, para HTML, devolve um retângulo que engloba as caixas de borda em relação à área de visualização.

contentRect mantém-se por retrocompatibilidade. Para obteres dimensões lógicas, usa contentBoxSize quando estiver disponível: inlineSize e blockSize seguem o modo de escrita. A opção box de observe() determina qual é a caixa cujas alterações acionam notificações; escolher border-box não faz com que contentRect passe a medir a caixa de borda. ECMAScript 2024 indica apenas a versão de referência da linguagem JavaScript. Ambas as propriedades são definidas pela especificação Resize Observer, não pelo ECMAScript, e a sua disponibilidade depende do ambiente de execução.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>ResizeObserverEntry example</title>
</head>
<body>
<script>
(() => {
  const box = document.createElement('div');
  Object.assign(box.style, {
    boxSizing: 'content-box',
    width: '120px',
    height: '60px',
    padding: '10px',
    border: '2px solid black'
  });
  document.body.append(box);

  const observer = new ResizeObserver(([entry]) => {
    const { width, height } = entry.contentRect;
    console.log(`${entry.target === box}: ${width} × ${height} CSS px`);
    observer.disconnect();
    box.remove();
  });
  observer.observe(box);
})();
</script>
</body>
</html>

Resultado

true: 120 × 60 CSS px

Guarda o exemplo num ficheiro `.html` e abre-o num navegador que suporte `ResizeObserver`. Abre a consola de desenvolvimento e recarrega a página. A primeira notificação apresenta `true: 120 × 60 CSS px`: `true` confirma a identidade do elemento e as dimensões excluem o espaçamento interior e as bordas. Em seguida, o código termina a observação e remove o elemento.

Lições relacionadas

  • JavaScript · Lição 32 · Intermédio · Versão: 3

Fontes