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

CKTIS / JavaScript

Altura e posição de deslocamento: offsetHeight, clientHeight e scrollTop

Distingue a altura exterior de um elemento, a altura da sua área interior e a posição atual do deslocamento vertical. Aprende a detetar o fim sem depender de uma igualdade numérica exata.

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

Sintaxe

element.offsetHeight       // HTMLElement, read-only
 element.clientHeight       // Element, read-only
 element.scrollTop          // Element, read
 element.scrollTop = y      // Element, write a vertical offset in CSS pixels

Estas propriedades pertencem ao DOM do navegador, não ao ECMAScript. offsetHeight pertence a HTMLElement; clientHeight e scrollTop pertencem a Element e são herdadas pelos elementos HTML. Acede-lhes numa instância de um elemento, por exemplo com el.clientHeight. Todas as medidas são expressas em píxeis CSS.

offsetHeight é a altura inteira da caixa no esquema da página e é só de leitura. Normalmente inclui o espaçamento interior (padding), os contornos e a barra de deslocamento horizontal, se for apresentada, mas não as margens. Ignora as transformações CSS; usa el.getBoundingClientRect().height para obter a altura do retângulo delimitador após a transformação.

clientHeight é a altura interior inteira e é só de leitura. Inclui o espaçamento interior, mas exclui os contornos, as margens e a barra de deslocamento horizontal. Ambas as alturas valem 0 se display: none no elemento ou num antepassado o deixar sem caixa. No elemento raiz do documento (body no modo quirks), clientHeight mede a altura da área de visualização sem a barra de deslocamento horizontal.

scrollTop lê ou define o deslocamento vertical em relação à origem. Normalmente vale 0 no topo, mas pode ser fracionário ou negativo, por exemplo com flex-direction: column-reverse. No Safari, o efeito de ressalto nos limites do deslocamento pode apresentar temporariamente valores fora do intervalo normal. A atribuição el.scrollTop = y permite deslocar o conteúdo com overflow: hidden, mas não com overflow: clip.

scrollHeight é a altura inteira de todo o conteúdo, incluindo o que transborda para fora da área visível, mais o espaçamento interior. Num contentor que se desloca normalmente para baixo, sem ultrapassar os limites, deteta o fim com Math.abs(el.scrollHeight - el.clientHeight - el.scrollTop) <= 1. Usa uma tolerância de um píxel CSS em vez de ===, porque scrollTop pode ser fracionário. Não reutilizes este teste sem alterações quando a disposição tem a direção invertida.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Element height and scroll position</title>
</head>
<body>
  <script>
    (() => {
      const box = document.createElement('div');
      box.style.cssText = 'position:fixed;top:0;left:0;width:160px;height:100px;' +
        'box-sizing:content-box;padding:0;border:4px solid;overflow:hidden;' +
        'scroll-behavior:auto;writing-mode:horizontal-tb;';
      const content = document.createElement('div');
      content.style.height = '300px';
      box.append(content);
      document.body.append(box);

      try {
        box.scrollTop = 40;
        console.log(`offsetHeight=${box.offsetHeight} clientHeight=${box.clientHeight} scrollHeight=${box.scrollHeight} scrollTop=${box.scrollTop}`);

        box.scrollTop = 1000;
        const atBottom = Math.abs(box.scrollHeight - box.clientHeight - box.scrollTop) <= 1;
        console.log(`scrollTop=${box.scrollTop} atBottom=${atBottom}`);
      } finally {
        box.remove();
      }
    })();
  </script>
</body>
</html>

Resultado

offsetHeight=108 clientHeight=100 scrollHeight=300 scrollTop=40
scrollTop=200 atBottom=true

Guarda o exemplo como ficheiro HTML, abre-o num navegador e verifica o resultado na consola de programação. Os contornos acrescentam 8 px a `offsetHeight`, mas não a `clientHeight`. A tentativa de deslocar até 1000 para em 200, o limite inferior.

Lições relacionadas

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

Fontes