SWCore / Componentes / Scroll (âncora suave)

Scroll (âncora suave) Componentes

Rolagem suave até uma seção da página ao clicar num link âncora.

O que é

Substitui o salto brusco do navegador ao clicar em <a href="#secao"> por uma rolagem animada, com espaço reservado pra uma navbar fixa.

Como funciona

Intercepta o clique, calcula a posição do alvo com getBoundingClientRect() e chama window.scrollTo({behavior:"smooth"}). Respeita prefers-reduced-motion (pula direto sem animação).

Exemplos

Padrão Ao vivo
Ir pra seção 2 ↓
role a página pra baixo, ou clique no botão acima ↑

Seção 2

Chegou aqui com rolagem suave e espaço reservado no topo (sw-scroll-offset) — não fica colado debaixo de uma navbar fixa.

<a sw-scroll href="#secao2">Ir pra seção 2</a>
...
<div id="secao2">...</div>
URL bonita + título + descrição + canônica (SEO) — página única se comportando como se tivesse rotas Ao vivo
Ir pra "/scroll-exemplo-a" Ir pra "/scroll-exemplo-b"

Repare na URL do navegador e no título da aba mudando ao clicar — sem hash, sem recarregar a página. Volte com o ← do navegador pra ver o histórico funcionando também.

Seção A · /scroll-exemplo-a

Esta seção virou uma "página" com URL, título, descrição e canônica próprios, mesmo sendo uma âncora normal na mesma página física.

Seção B · /scroll-exemplo-b

Recarregar a página numa dessas URLs exige que o servidor sirva o mesmo HTML pra qualquer caminho (rewrite/fallback de SPA) — nesta doc isso não está configurado, então F5 aqui dá 404 de propósito; no seu site é você quem configura essa parte do servidor.

Estado real do <head> agora:

título: —
meta description: —
link canonical: —
<!-- O link continua sendo um <a href="#id"> normal -->
<a sw-scroll href="#sobre">Sobre</a>

<!-- Quem declara URL bonita, título, descrição e canônica é o DESTINO, não o link -->
<section id="sobre"
  sw-scroll-path="/sobre"
  sw-scroll-title="Sobre nós — Minha Empresa"
  sw-scroll-desc="Conheça a história e os valores da empresa."
  sw-scroll-canonical>
  ...
</section>

<!-- Recarregar em /sobre, ou usar voltar/avançar do navegador, também funciona -->
<!-- Exige rewrite no servidor: qualquer caminho registrado precisa servir este mesmo HTML -->

Atributos

sw-scroll-target
no link — seletor do alvo (se diferente do href)
sw-scroll-offset
no link ou no destino — pixels de espaço reservado no topo (padrão 80, pra navbar fixa)
sw-scroll-path
no elemento destino — URL bonita pra essa seção (ex.: "/sobre"), trocada via History API em vez do #hash feio
sw-scroll-title
no elemento destino — título da aba pra essa seção, trocado junto com a URL (SEO)
sw-scroll-desc
no elemento destino — troca o <meta name="description"> da página pra essa seção
sw-scroll-canonical
no elemento destino (sem valor) — atualiza <link rel="canonical"> pra apontar pro sw-scroll-path dessa seção

Variantes

Nenhum.

Eventos

sw:scroll:arrived
disparado no elemento alvo ao terminar de rolar

API (JavaScript)

SW.Scroll.to(sel, offset?)
rola por código, sem precisar de um link
SW.Scroll.goto(path)
navega por código pro caminho bonito registrado (equivale a clicar num link que aponta pra ele)

Requisitos

Nenhuma.

Limitações — o que ele não faz

  • O href precisa começar com # e apontar pra um id que exista na página.
  • sw-scroll-path muda a URL só no navegador (History API) — pra ela sobreviver a um F5 ou a um acesso direto, o servidor precisa servir este mesmo HTML pra qualquer caminho registrado (configuração de servidor, fora do componente).
← AnteriorSidebar Próximo →Scrollspy