O que GSAP Timeline faz?
Quando Usar Esta Habilidade
Aplique ao construir animações multi-etapas, coordenando vários tweens em sequência ou paralelo, ou quando o usuário perguntar sobre timelines, sequenciamento ou animação estilo quadro-chave no GSAP.
Habilidades relacionadas: Para tweens únicos e eases use gsap-core; para timelines acionadas 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 anexados um após o outro. Use o parâmetro de posição para posicionar tweens em momentos específicos ou relativamente a outros tweens.
Parâmetro de Posição
O terceiro argumento (ou propriedade position em vars) controla o posicionamento:
- Absoluto:
1— inicia em 1 segundo. - Relativo (padrão):
"+=0.5"— 0.5s após o fim;"-=0.2"— 0.2s antes do fim. - Label:
"labelName"— naquele label;"labelName+=0.3"— 0.3s após o label. - Posicionamento:
"<"— inicia quando a animação adicionada recentemente inicia;">"— inicia 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); // em 0
tl.to(".b", { y: 50 }, "+=0.5"); // 0.5s após o último fim
tl.to(".c", { opacity: 0 }, "<"); // mesmo início do anterior
tl.to(".d", { scale: 2 }, "<0.2"); // 0.2s após o início do anterior
Defaults da Timeline
Passe defaults 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 }); // ambos usam 0.5s e power2.out
Opções da Timeline (construtor)
- paused: true — cria pausada; chame
.play()para iniciar. - repeat, yoyo — mesmas opções dos tweens; aplicam-se à timeline inteira.
- onComplete, onStart, onUpdate — callbacks no nível da timeline.
- defaults — vars mescladas em cada tween filho.
Labels
Adicione e use labels 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"); // inicia a partir de "outro"
tl.tweenFromTo("intro", "outro"); // pausa a timeline e retorna um novo Tween que anima o playhead da timeline de intro até outro sem suavização.
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) depois tl.reverse()
- tl.restart() — do início.
- tl.time(2) — avança para 2 segundos.
- tl.progress(0.5) — avança para 50%.
- tl.kill() — mata a timeline e (por padrão) seus filhos.
Boas Práticas Oficiais do GSAP
- ✅ Prefira timelines para sequenciamento
- ✅ Use o parâmetro de posição (terceiro argumento) para posicionar tweens em momentos específicos ou relativos a labels.
- ✅ Adicione labels com
addLabel()para sequenciamento legível e de fácil manutenção. - ✅ Passe defaults no construtor da timeline para que tweens filhos herdem duração, ease, etc.
- ✅ Coloque ScrollTrigger na timeline (ou tween de nível superior), não em tweens dentro de uma timeline.
Não Faça
- ❌ Encadeie animações com delay quando uma timeline pode sequenciá-las; prefira
gsap.timeline()e o parâmetro de posição para animação multi-etapas. - ❌ Esqueça de passar defaults (ex.:
defaults: { duration: 0.5, ease: "power2.out" }) quando muitos tweens filhos compartilham a mesma duração ou ease. - ❌ Esqueça que duration no construtor da timeline não é o mesmo que duração do tween; a “duração” da timeline é determinada por seus filhos.
- ❌ Aninhe animações que contenham um ScrollTrigger; ScrollTriggers devem estar apenas em Tweens/Timelines de nível superior.