Métodos de Rolagem em JavaScript: Guia Completo

Existem 4 métodos no objeto window: scrollX, scrollY, scrollTo, scroll (o scroll tem a mesma função que scrollTo)

E 4 propriedades no objeto Element: scrollWidth, scrollHeight, scrollLeft, scrollTop

Objeto window (BOM)

window.scrollX e window.scrollY


var posX = window.scrollX;  // Retorna em pixels a largura rolada do documento no eixo horizontal
var posY = window.scrollY;  // Retorna em pixels a altura rolada do documento no eixo vertical

A propriedade pageYOffset é um apelido para scrollY, e pageXOffset para scrollX. Para compatibilidade entre navegadores, geralmente utiliza-se os primeiros (pageYOffset, pageXOffset).

Versões antigas de navegaodres (<9) não suportam essas propriedades, exigindo o uso de propriedades não padrão.

Código de compatibilidade para obter a distância de rolagem vertical e horizontal da página:


var temSuportePageOffset = window.pageXOffset !== undefined;
var modoCSS1Compat = ((document.compatMode || "") === "CSS1Compat");

var posX = temSuportePageOffset ? window.pageXOffset : modoCSS1Compat ? document.documentElement.scrollLeft : document.body.scrollLeft;
var posY = temSuportePageOffset ? window.pageYOffset : modoCSS1Compat ? document.documentElement.scrollTop : document.body.scrollTop;

window.scrollTo(x, y)

Este método rola a janela para as coordenadas especificadas, tendo como origem o canto superior esquerdo do documento.


window.scrollTo(100, 500); // Rola para 100px da esquerda e 500px do topo

Não requer tratamento de compatibilidade.

window.scroll(x, y)

Funciona exatamente como window.scrollTo().

Objeto Element (DOM)

scrollWidth

Propriedade somente leitura que retorna o maior valor entre a largura do conteúdo e a largura do próprio elemento. Se o elemento tiver barra de rolagem, scrollWidth será maior que clientWidth.

Observação: Esta propriedade retorna um valor inteiro arredondado. Para precisão decimal, utilize Element.getBoundingClientRect().


var larguraRolagem = elemento.scrollWidth;

scrollHeight

Propriedade somente leitura que retorna a altura total do conteúdo do elemento, incluindo partes não visíveis devido ao overflow. Inclui padding, mas não margin.


var alturaRolagem = elemento.scrollHeight;

Aplicação prática: verificar se um elemento foi rolado até o final


function estaNoFinal(elemento) {
    return elemento.scrollHeight - elemento.scrollTop === elemento.clientHeight;
}

scrollLeft

Propriedade que obtém ou define a posição da barra de rolagem horizontal do elemento.


// Obter a posição atual da rolagem horizontal
var posEsquerda = elemento.scrollLeft;

// Definir a posição da rolagem horizontal
elemento.scrollLeft = 50;

scrollTop

Propriedade que obtém ou define a posição da barra de rolagem vertical do elemento.


// Obter a posição atual da rolagem vertical
var posTopo = elemento.scrollTop;

// Definir a posição da rolagem vertical
elemento.scrollTop = 100;

Código de compatibilidade para obter e definir a posição de rolagem vertical:


// Obter a posição de rolagem vertical
function obterRolagemVertical() {
    return window.pageYOffset || document.documentElement.scrollTop;
}

// Definir a posição de rolagem vertical
function definirRolagemVertical(valor) {
    document.body.scrollTop = document.documentElement.scrollTop = valor;
}

Observação Importante

É comum confundir os métodos do objeto window (scrollY/pageYOffset, scrollX/pageXOffset) com as propriedades do objeto Element (scrollTop, scrollLeft). Eles têm propósitos diferentes: os primeiros obtêm a distância de rolagem da janela, enquanto os segundos obtêm a distância de rolagem de um elemento específico. Quando o elemento em questão é o body, window.scrollY equiavle a document.body.scrollTop.

Dimensões da Janela do Navegador

Para obter informações sobre as dimensões da janela do navegador:


function obterInfoJanela() {
    var info = "";
    info += " Largura da área visível: " + window.innerWidth;
    info += " Altura da área visível: " + window.innerHeight;
    info += " Largura total do documento: " + document.documentElement.scrollWidth;
    info += " Altura total do documento: " + document.documentElement.scrollHeight;
    return info;
}

Obtendo Dimensões Precisas do Cliante


var larguraCliente, alturaCliente, larguraRolagem, alturaRolagem, posEsquerda, posTopo;

if (document.compatMode === "BackCompat") {
    larguraCliente = document.body.clientWidth;
    alturaCliente = document.body.clientHeight;
    larguraRolagem = document.body.scrollWidth;
    alturaRolagem = document.body.scrollHeight;
    posEsquerda = document.body.scrollLeft;
    posTopo = document.body.scrollTop;
} else {
    larguraCliente = document.documentElement.clientWidth;
    alturaCliente = document.documentElement.clientHeight;
    larguraRolagem = document.documentElement.scrollWidth;
    alturaRolagem = document.documentElement.scrollHeight;
    posEsquerda = document.documentElement.scrollLeft || document.body.scrollLeft;
    posTopo = document.documentElement.scrollTop || document.body.scrollTop;
}

Tags: javascript DOM scroll compatibilidade navegador

Publicado em 8-9 16:58