GSAP Timeline

Selecionado das habilidades oficiais do GSAP da GreenSock: https://github.com/greensock/gsap-skills

Quando Usar Esta Habilidade

Aplique ao construir animações de múltiplos passos, coordenar vários tweens em sequência ou paralelamente, ou quando o usuário perguntar sobre timelines, sequenciamento ou animação no estilo keyframe no GSAP.

Habilidades relacionadas: Para tweens e eases únicos, use gsap-core; para timelines controladas por scroll, use gsap-scrolltrigger; para React, use gsap-react.

Criando uma Timeline

const tl = gsap.timeline();
tl.to(".a", { x: 100, duration: 1 })
  .to(".b", { y: 50, duration: 0.5 })
  .to(".c", { opacity: 0, duration: 0.3 });

Por padrão, os tweens são adicionados um após o outro. Use o parâmetro de posição para colocar tweens em tempos específicos ou em relação a outros tweens.

Parâmetro de Posição

Terceiro argumento (ou propriedade de posição em vars) controla a colocação:

• Absoluto: 1 — começa em 1 segundo.
• Relativo (padrão): "+=0.5" — 0,5s após o fim; "-=0.2" — 0,2s antes do fim.
• Rótulo: "labelName" — naquele rótulo; "labelName+=0.3" — 0,3s após o rótulo.
• Colocação: "<" — começa quando a animação adicionada recentemente começa; ">" — começa quando a animação adicionada recentemente termina (padrão); "<0.2" — 0,2s após o início da animação adicionada recentemente.

Exemplos:

tl.to(".a", { x: 100 }, 0);           // at 0
tl.to(".b", { y: 50 }, "+=0.5");      // 0.5s after last end
tl.to(".c", { opacity: 0 }, "<");     // same start as previous
tl.to(".d", { scale: 2 }, "<0.2");    // 0.2s after previous start

Padrões da Timeline

Passe padrões para a timeline para que todos os tweens filhos herdem:

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out

Opções da Timeline (construtor)

• paused: true — cria pausada; chame .play() para iniciar.
• repeat, yoyo — igual a tweens; aplique à timeline inteira.
• onComplete, onStart, onUpdate — callbacks no nível da timeline.
• defaults — vars mescladas em cada tween filho.

Rótulos

Adicione e use rótulos para sequenciamento legível e de fácil manutenção:

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro");  // start from "outro"
tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.

Aninhando Timelines

Timelines podem conter outras timelines.

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
master.to(".c", { opacity: 0 }, "+=0.2");

Controlando a Reprodução

• tl.play() / tl.pause()
• tl.reverse() / tl.progress(1) então tl.reverse()
• tl.restart() — do início.
• tl.time(2) — busca para 2 segundos.
• tl.progress(0.5) — busca para 50%.
• tl.kill() — mata a timeline e (por padrão) seus filhos.

Melhores Práticas Oficiais do GSAP

• ✅ Prefira timelines para sequenciamento
• ✅ Use o parâmetro de posição (terceiro argumento) para colocar tweens em tempos específicos ou em relação a rótulos.
• ✅ Adicione rótulos com addLabel() para sequenciamento legível e de fácil manutenção.
• ✅ Passe padrões para o construtor da timeline para que os tweens filhos herdem duração, ease, etc.
• ✅ Coloque ScrollTrigger na timeline (ou tween de nível superior), não nos tweens dentro de uma timeline.

Não Faça

• ❌ Encadear animações com delay quando uma timeline pode sequenciá-las; prefira gsap.timeline() e o parâmetro de posição para animação de múltiplos passos.
• ❌ Esquecer de passar padrões (ex: defaults: { duration: 0.5, ease: "power2.out" }) quando muitos tweens filhos compartilham a mesma duração ou ease.
• ❌ Esquecer que a duração no construtor da timeline não é a mesma que a duração do tween; a "duração" da timeline é determinada por seus filhos.
• ❌ Aninhar animações que contêm um ScrollTrigger; ScrollTriggers devem estar apenas em Tweens/Timelines de nível superior.