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

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 Number

element.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

Fontes