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

CKTIS / JavaScript

DOMRect: limite superior (`top`) e altura (`height`)

`top` indica a posição do limite superior do retângulo e `height` indica a sua altura com sinal. São propriedades distintas, quer cries um retângulo, quer meças um elemento.

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

Sintaxe

rect.top
rect.height
new DOMRect(x, y, width, height)
element.getBoundingClientRect()

rect.top e rect.height são propriedades de instância, não métodos. top é a coordenada vertical do limite superior. height é a altura com sinal, não uma coordenada. Ambos os valores são números e podem ter uma parte fracionária.

Para valores finitos de y e height, top vale y + height se height < 0, e y caso contrário. Uma altura negativa num retângulo criado manualmente mantém-se negativa: não é convertida no seu valor absoluto. Num DOMRect, podes atribuir um valor a height, e a leitura de top reflete a alteração. top é só de leitura em ambas as interfaces; height também é só de leitura em DOMRectReadOnly.

No resultado de element.getBoundingClientRect(), ambos os valores são expressos em píxeis CSS. top é medido em relação ao limite superior da área de visualização e pode ser negativo se o limite superior do retângulo estiver acima dela. height é a altura não negativa do retângulo delimitador, que tem em conta o espaçamento interior (padding) e as bordas, não apenas o conteúdo. O resultado não se atualiza automaticamente: volta a chamar o método depois de deslocares a página ou de uma alteração na disposição dos elementos, para obteres uma nova medição. Alterar o retângulo devolvido não altera o elemento.

DOMRect é uma API Web e não faz parte do ECMAScript 2024. Não partas do princípio de que está disponível em todos os ambientes de execução de JavaScript.

Exemplos

{
  const y = 20;
  const height = 8;

  // Without DOMRect, model only top and signed height for finite values.
  const rect = typeof DOMRect === "function"
    ? new DOMRect(0, y, 10, height)
    : {
        y,
        height,
        get top() {
          return this.height < 0 ? this.y + this.height : this.y;
        },
      };

  console.log(`top=${rect.top}, height=${rect.height}`);

  rect.height = -8;
  console.log(`top=${rect.top}, height=${rect.height}`);
}

Resultado

top=20, height=8
top=12, height=-8

O exemplo não precisa de um elemento da página. `y` mantém-se em `20`, mas, depois de atribuíres `height = -8`, o limite superior passa para `12`.

Lições relacionadas

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

Fontes