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