Frames (sprite no scroll) Animações

O que é

Em vez de um vídeo, você tem várias fotos em sequência (o produto fotografado girando, as etapas de uma montagem, os cômodos de um imóvel). O Frames mostra uma de cada vez, ocupando a tela, e troca para a próxima conforme a pessoa rola: rolou para baixo, avança; rolou para cima, volta. A troca é seca, de foto em foto, como folhear.

O bloco sw-ani="frames" fica mais alto que a tela (para ter rolagem) e o palco sw-ani-frame-stage, dentro dele, fica grudado na tela enquanto isso. Os quadros podem vir de duas formas: várias imagens (cada uma com sw-ani-frame) ou um sprite — uma imagem só com todos os quadros em grade, que você põe como fundo do palco e descreve com sw-ani-frame-sprite="colunasxlinhas". Precisa do pacote de animação.

Quando usar

• Produto girando 360° (tênis, relógio, móvel) numa página de venda.
• Passo a passo visual: montagem, antes/depois em etapas, evolução de uma obra.
• Tour por um lugar: cômodos de um imóvel, ambientes de um restaurante.
• Para movimento contínuo e suave (não quadro a quadro), o caminho é um vídeo preso à rolagem, não este componente.

Comece aqui

1. 1

   Coloque o SW Core e o pacote de animação. O JS da animação vai antes do swcore.min.js.

   <link rel="stylesheet" href="swcore/swcore.min.css">
   <link rel="stylesheet" href="swcore/swcore.motion.min.css">
   
   <!-- fim do <body> -->
   <script src="swcore/swcore.motion.min.js"></script>
   <script src="swcore/swcore.min.js"></script>

2. 2

   O bloco, o palco (filho direto) e as imagens dentro do palco, na ordem. Os exemplos ao vivo estão logo abaixo — eles ocupam a tela inteira.

   <div sw-ani="frames" sw-ani-end="200%">
     <div sw-ani-frame-stage>
       <img sw-ani-frame src="/giro/01.webp" alt="Tênis, vista de frente">
       <img sw-ani-frame src="/giro/02.webp" alt="">
       <img sw-ani-frame src="/giro/03.webp" alt="">
       <!-- … -->
     </div>
   </div>

Todas as variações

Cada quadro abaixo é o componente de verdade, rodando. O código embaixo é exatamente o que está no quadro: copie e cole.

Tabela de opções

Receitas prontas — usos reais

Situações que aparecem em quase todo site. Copie a que servir.

Essa seção prende a tela de verdade e se solta da moldura enquanto você rola — role bem devagar pra ver o efeito.

<div sw-ani="frames" sw-ani-end="250%">
  <div sw-ani-frame-stage>
    <img sw-ani-frame src="/imovel/fachada.webp" width="1200" height="800" alt="Fachada">
    <img sw-ani-frame src="/imovel/sala.webp" width="1200" height="800" alt="Sala de estar">
    <img sw-ani-frame src="/imovel/varanda.webp" width="1200" height="800" alt="Vista da varanda">
    <!-- … -->
  </div>
</div>

<p id="contador">1 de 24</p>

<script>
  document.querySelector('[sw-ani="frames"]').addEventListener('sw:frame', (e) => {
    document.getElementById('contador').textContent = (e.detail.index + 1) + ' de ' + e.detail.total;
  });
</script>

<!-- dentro de um Sections, quem dá a rolagem é a TELA (sw-ani-h nela) -->
<div sw-ani="sections" sw-ani-fx="cover|fade">
  <section sw-ani-section sw-ani-h="300%">
    <div sw-ani="frames">
      <div sw-ani-frame-stage>
        <img sw-ani-frame src="/giro/01.webp" alt="">
        <img sw-ani-frame src="/giro/02.webp" alt="">
        <!-- … -->
      </div>
    </div>
    <p sw-ani="move" sw-ani-distance="60">Legenda que sobe junto com os quadros</p>
  </section>
  <section sw-ani-section>Próxima tela</section>
</div>

Eventos

API (JavaScript)

Precisa de quê

• swcore.min.css + swcore.motion.min.css, e swcore.motion.min.js antes do swcore.min.js.

Cuidados — erros comuns

• O palco tem que ser filho direto do bloco. Sem palco, nada acontece (aviso no console).
• No sprite, o SW Core não coloca a imagem: ponha o background-image no palco pelo seu CSS (como no exemplo). Sem isso, o palco fica vazio.
• No sprite, cada quadro é esticado para o tamanho do palco. Se o palco não tiver o mesmo formato de um quadro, a imagem deforma — ajuste o formato do palco (aspect-ratio).
• sw-ani-frame-count só vale para sprite. Com várias imagens, o total é o número de sw-ani-frame.
• Todas as imagens precisam estar carregadas para a troca ser instantânea. Comprima bem e prefira 24–36 quadros a 60.
• Quadros com tamanhos/proporções diferentes "pulam" na troca: gere todos iguais.

O que ele não faz

• É o componente mais pesado da família: todos os quadros ficam na página. Meça o peso total antes de publicar.
• A troca é seca, de imagem em imagem — não existe transição suave entre quadros.
• Quem ativou "reduzir movimento" no aparelho vê só o primeiro quadro, em uma tela, sem rolagem extra.