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 pixelsEstas 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