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

CKTIS / JavaScript

Element.getBoundingClientRect(): dimensões e posição de um DOMRect

Mede o retângulo delimitador de um elemento em píxeis CSS e distingue as coordenadas da área de visualização das coordenadas do documento.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const rect = element.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;

element.getBoundingClientRect() não recebe argumentos e devolve um DOMRect. É uma API Web, não faz parte do ECMAScript. A medição exige um ambiente capaz de calcular a disposição do DOM; a disponibilidade depende do ambiente de execução.

Num elemento HTML, a medição baseia-se em retângulos alinhados com os eixos que correspondem às caixas CSS até ao limite exterior da borda. Inclui o espaçamento interior e a borda, tem em conta as transformações CSS e exclui as margens. Usa getClientRects() para obter os retângulos separadamente. Se a lista estiver vazia, como com display: none, todos os valores são zero. Se cada retângulo tiver largura ou altura igual a zero, o método devolve o primeiro retângulo da lista. Caso contrário, devolve o menor retângulo que abrange todos os da lista, exceto os que têm as duas dimensões iguais a zero. Se um elemento em linha ocupar várias linhas, o resultado pode incluir espaços entre fragmentos. O retângulo, por si só, não prova que o elemento esteja visível.

width e height são as dimensões do retângulo. Neste resultado, x e y coincidem com left e top; right é left + width e bottom é top + height. As coordenadas são medidas a partir do canto superior esquerdo da área de visualização, não do lado mais próximo, e podem ser negativas. Todos os valores são em píxeis CSS e podem ser fracionários.

Num DOMRect, x, y, width e height podem ser alterados; as coordenadas dos lados são calculadas e só de leitura. Num retângulo criado manualmente com width ou height negativos, x pode diferir de left ou y de top. Alterar o resultado não altera o elemento. O resultado não se atualiza por si só: volta a medir se precisares de valores atuais depois de uma alteração na disposição ou de uma deslocação do conteúdo.

Para obter o canto superior esquerdo nas coordenadas do documento, usa rect.left + window.scrollX e rect.top + window.scrollY, lendo os valores de deslocação no momento da medição. Isto muda a origem das coordenadas, mas não anula a deslocação dentro de um contentor aninhado.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Measuring an element</title>
</head>
<body>
<script>
(() => {
  const box = document.createElement('div');
  box.style.cssText = 'position: fixed; left: 24.5px; top: 16px; margin: 0; box-sizing: content-box; width: 104px; height: 44px; padding: 8px; border: 0;';
  document.body.append(box);
  try {
    const rect = box.getBoundingClientRect();
    const { x, y, width, height, top, right, bottom, left } = rect;
    console.log(`x=${x}, y=${y}, width=${width}, height=${height}, top=${top}, right=${right}, bottom=${bottom}, left=${left}`);

    box.style.left = '44.5px';
    console.log(`previous x=${rect.x}, current x=${box.getBoundingClientRect().x}`);
  } finally {
    box.remove();
  }
})();
</script>
</body>
</html>

Resultado

x=24.5, y=16, width=120, height=60, top=16, right=144.5, bottom=76, left=24.5
previous x=24.5, current x=44.5

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta o resultado na consola de programação. As dimensões incluem o espaçamento interior dos dois lados de cada eixo; o elemento não tem borda. Depois de moveres o elemento, o retângulo anterior mantém o seu `x` original; só uma nova medição devolve o novo `x`.

Lições relacionadas

  • JavaScript · Lição 12 · Avançado · Versão: 4

Fontes