CKTIS / JavaScript
Retângulo delimitador e deslocamentos da área cliente
Mede a posição e o tamanho de um elemento em relação à área de visualização e distingue essas medidas dos deslocamentos esquerdo e superior da área cliente.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
element.getBoundingClientRect() // DOMRect
element.clientLeft // integer Number
element.clientTop // integer Numberelement.getBoundingClientRect() é um método de Element que não recebe argumentos. Devolve um DOMRect calculado a partir dos retângulos que getClientRects() fornece para as caixas de borda depois de aplicadas as transformações. Se a lista estiver vazia, todos os valores são zero. Se cada retângulo da lista 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 alinhado com os eixos que engloba os retângulos com largura ou altura diferente de zero. Inclui o espaçamento interior e as bordas, mas não as margens. left e top são coordenadas relativas ao canto superior esquerdo da área de visualização; width e height são dimensões. Os valores são dados em píxeis CSS e podem ser fracionários.
element.clientLeft e element.clientTop são propriedades só de leitura, não métodos. Devolvem deslocamentos inteiros em píxeis CSS, sem considerar as transformações: a espessura das bordas esquerda e superior, respetivamente, mais o espaço ocupado por uma barra de deslocamento do mesmo lado. Uma barra vertical pode ficar à esquerda, por exemplo numa disposição da direita para a esquerda. O espaçamento interior e a margem não contam. Ambas as propriedades devolvem zero para uma caixa em linha ou na ausência de caixa CSS.
O DOMRect é um registo da medição que não se atualiza por si só. Volta a medir depois de deslocares a página ou de alterares a disposição, se precisares de coordenadas atualizadas. Para obter coordenadas relativas ao documento, soma window.scrollX a left e window.scrollY a top. Não uses clientLeft e clientTop como coordenadas da área de visualização nem como forma geral de converter coordenadas após uma transformação. Estas API pertencem à plataforma web (CSSOM View), não ao ECMAScript 2024; a disponibilidade depende do ambiente de execução.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Element geometry</title>
</head>
<body>
<script>
(() => {
// Use a 1:1 ratio so the borders need no device-pixel rounding.
if (window.devicePixelRatio !== 1) {
throw new Error('Run at 100% page zoom with devicePixelRatio set to 1.');
}
const box = document.createElement('div');
box.style.cssText = `
position: fixed; left: 20px; top: 30px;
box-sizing: border-box; width: 80px; height: 40px;
border: solid black; border-width: 5px 2px 2px 3px;
overflow: hidden; transform-origin: top left; transform: scale(2);
`;
document.body.append(box);
try {
const { left, top, width, height } = box.getBoundingClientRect();
console.log(`rect: ${left}, ${top}, ${width}, ${height}`);
console.log(`client: ${box.clientLeft}, ${box.clientTop}`);
} finally {
box.remove();
}
})();
</script>
</body>
</html>Resultado
rect: 20, 30, 160, 80 client: 3, 5
Abre o documento HTML num navegador com a ampliação da página a 100% e `devicePixelRatio` igual a `1`. Consulta o resultado na consola do navegador. A escala duplica as dimensões do retângulo sem deslocar o canto superior esquerdo; os deslocamentos mantêm-se em `3` e `5`.
Lições relacionadas
- JavaScript · Lição 35 · Avançado · Versão: 4