Línea de tiempo de GSAP
Cuándo usar esta habilidad
Aplícala al construir animaciones de varios pasos, coordinar varios tweens en secuencia o en paralelo, o cuando el usuario pregunte sobre líneas de tiempo, secuenciación o animación al estilo de fotogramas clave en GSAP.
Habilidades relacionadas: Para tweens individuales y suavizaciones (eases) usa gsap-core; para líneas de tiempo controladas por scroll usa gsap-scrolltrigger; para React usa gsap-react.
Crear una línea de tiempo
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 defecto, los tweens se añaden uno tras otro. Usa el parámetro de posición para colocar tweens en momentos específicos o en relación con otros tweens.
Parámetro de posición
El tercer argumento (o la propiedad position en vars) controla la colocación:
- Absoluto:
1— comienza en 1 segundo. - Relativo (predeterminado):
"+=0.5"— 0.5 s después del final;"-=0.2"— 0.2 s antes del final. - Etiqueta:
"labelName"— en esa etiqueta;"labelName+=0.3"— 0.3 s después de la etiqueta. - Colocación:
"<"— comienza cuando comienza la animación agregada recientemente;">"— comienza cuando termina la animación agregada recientemente (predeterminado);"<0.2"— 0.2 s después de que comience la animación agregada recientemente.
Ejemplos:
tl.to(".a", { x: 100 }, 0); // en 0
tl.to(".b", { y: 50 }, "+=0.5"); // 0.5 s después del último final
tl.to(".c", { opacity: 0 }, "<"); // mismo inicio que el anterior
tl.to(".d", { scale: 2 }, "<0.2"); // 0.2 s después del inicio anterior
Valores predeterminados de la línea de tiempo
Pasa valores predeterminados a la línea de tiempo para que todos los tweens hijos los hereden:
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // ambos usan 0.5 s y power2.out
Opciones de la línea de tiempo (constructor)
- paused: true — crea pausada; llama a
.play()para iniciar. - repeat, yoyo — igual que en tweens; se aplican a toda la línea de tiempo.
- onComplete, onStart, onUpdate — callbacks a nivel de línea de tiempo.
- defaults — vars fusionadas en cada tween hijo.
Etiquetas
Agrega y usa etiquetas para una secuenciación legible y mantenible:
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro"); // comienza desde "outro"
tl.tweenFromTo("intro", "outro"); // pausa la línea de tiempo y devuelve un nuevo Tween que anima el cabezal de reproducción desde intro hasta outro sin suavización.
Anidar líneas de tiempo
Las líneas de tiempo pueden contener otras líneas de tiempo.
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");
Controlar la reproducción
- tl.play() / tl.pause()
- tl.reverse() / tl.progress(1) luego tl.reverse()
- tl.restart() — desde el inicio.
- tl.time(2) — saltar a 2 segundos.
- tl.progress(0.5) — saltar al 50%.
- tl.kill() — destruir la línea de tiempo y (por defecto) sus hijos.
Buenas prácticas oficiales de GSAP
- ✅ Prefiere líneas de tiempo para secuenciar.
- ✅ Usa el parámetro de posición (tercer argumento) para colocar tweens en momentos específicos o en relación con etiquetas.
- ✅ Agrega etiquetas con
addLabel()para una secuenciación legible y mantenible. - ✅ Pasa valores predeterminados en el constructor de la línea de tiempo para que los tweens hijos hereden duración, suavización, etc.
- ✅ Coloca ScrollTrigger en la línea de tiempo (o en el tween de nivel superior), no en tweens dentro de una línea de tiempo.
Qué no hacer
- ❌ No encadenes animaciones con delay cuando una línea de tiempo pueda secuenciarlas; prefiere
gsap.timeline()y el parámetro de posición para animaciones de varios pasos. - ❌ No olvides pasar valores predeterminados (ej.
defaults: { duration: 0.5, ease: "power2.out" }) cuando muchos tweens hijos compartan la misma duración o suavización. - ❌ No olvides que la duración en el constructor de la línea de tiempo no es lo mismo que la duración del tween; la "duración" de la línea de tiempo está determinada por sus hijos.
- ❌ No anides animaciones que contengan un ScrollTrigger; los ScrollTrigger solo deben estar en Tweens/Líneas de tiempo de nivel superior.