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

CKTIS / JavaScript

HTMLElement.style.scrollBehavior — configurar o deslocamento suave

Lê, define ou remove a declaração CSS em linha `scroll-behavior` de um elemento e distingue-a do valor CSS resolvido e da opção de uma única chamada de deslocamento.

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

Sintaxe

element.style.scrollBehavior;
element.style.scrollBehavior = "smooth";
element.style.scrollBehavior = "auto";
element.style.scrollBehavior = "";

HTMLElement.style.scrollBehavior é uma propriedade do CSSOM no objeto style de uma instância de um elemento HTML. Não é uma propriedade estática do construtor HTMLElement nem faz parte do ECMAScript. Usa element.style.scrollBehavior para ler ou alterar a declaração CSS em linha de scroll-behavior.

Sem uma declaração em linha, a leitura devolve "", mesmo que uma folha de estilos defina a propriedade. Atribuir "" elimina apenas essa declaração; atribuir "auto" define-a explicitamente. Num elemento ligado ao documento, usa getComputedStyle(element).scrollBehavior para consultar o valor resolvido após a aplicação da cascata.

Definir a propriedade não inicia o deslocamento. Controla como um contentor se desloca quando o movimento é desencadeado pela navegação, por exemplo através de uma ligação para um fragmento da página, ou por uma API de deslocamento do CSSOM. Não altera o deslocamento direto com a roda do rato ou um gesto. Em CSS, auto é o valor inicial e indica deslocamento instantâneo; smooth solicita uma animação cuja duração e curva de progressão são escolhidas pelo navegador. A propriedade não é herdada por omissão e o navegador pode ignorá-la.

Para configurar o deslocamento da área visível de uma página HTML, usa o elemento raiz (document.documentElement); uma declaração em document.body não se propaga para essa área. Em element.scrollTo({ top: 100, behavior: "auto" }), "auto" segue o CSS; "smooth" e "instant" escolhem o comportamento apenas para essa chamada. "instant" não é um valor CSS válido para scroll-behavior. Evita forçar o deslocamento suave quando se verifica prefers-reduced-motion: reduce.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Inline scroll behavior</title>
</head>
<body>
  <script>
    const element = document.createElement("div");
    console.log(JSON.stringify(element.style.scrollBehavior));
    element.style.scrollBehavior = "smooth";
    console.log(JSON.stringify(element.style.getPropertyValue("scroll-behavior")));
    element.style.scrollBehavior = "";
    console.log(JSON.stringify(element.style.scrollBehavior));
  </script>
</body>
</html>

Resultado

""
"smooth"
""

O exemplo usa um elemento desligado do documento para ler, definir e remover a declaração sem deslocar a página. `JSON.stringify()` mostra a cadeia vazia como `""`.

Lições relacionadas

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

Fontes