GSAP 타임라인
이 스킬을 사용해야 할 때
다단계 애니메이션을 만들거나, 여러 트윈을 순차적으로 또는 병렬로 조율해야 할 때, 사용자가 타임라인, 시퀀싱, GSAP의 키프레임 스타일 애니메이션에 대해 질문할 때 적용하세요.
관련 스킬: 단일 트윈과 이징은 gsap-core; 스크롤 기반 타임라인은 gsap-scrolltrigger; React는 gsap-react.
타임라인 생성
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 });
기본적으로 트윈은 하나씩 추가됩니다. 위치 파라미터를 사용하여 트윈을 특정 시간 또는 다른 트윈에 상대적으로 배치하세요.
위치 파라미터
세 번째 인수(또는 vars 객체의 position 속성)로 배치를 제어합니다:
- 절대적:
1— 1초에 시작. - 상대적 (기본):
"+=0.5"— 끝에서 0.5초 후;"-=0.2"— 끝에서 0.2초 전. - 레이블:
"labelName"— 해당 레이블에서;"labelName+=0.3"— 레이블에서 0.3초 후. - 배치:
"<"— 최근에 추가된 애니메이션의 시작과 함께 시작;">"— 최근에 추가된 애니메이션의 끝과 함께 시작 (기본);"<0.2"— 최근에 추가된 애니메이션 시작 후 0.2초 후.
예시:
tl.to(".a", { x: 100 }, 0); // 0초에
tl.to(".b", { y: 50 }, "+=0.5"); // 마지막 끝에서 0.5초 후
tl.to(".c", { opacity: 0 }, "<"); // 이전과 같은 시작
tl.to(".d", { scale: 2 }, "<0.2"); // 이전 시작 후 0.2초 후
타임라인 기본값
타임라인에 기본값을 전달하여 모든 하위 트윈이 상속받게 합니다:
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // 둘 다 0.5초와 power2.out 사용
타임라인 옵션 (생성자)
- paused: true — 일시 정지 상태로 생성;
.play()로 시작. - repeat, yoyo — 트윈과 동일; 타임라인 전체에 적용.
- onComplete, onStart, onUpdate — 타임라인 레벨 콜백.
- defaults — 모든 하위 트윈에 병합되는 vars.
레이블
레이블을 추가하고 사용하여 가독성 좋고 유지보수 쉬운 시퀀스를 만듭니다:
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro"); // "outro"부터 시작
tl.tweenFromTo("intro", "outro"); // 타임라인을 일시 정지하고 intro에서 outro로 재생 헤드를 애니메이션하는 새로운 트윈을 반환합니다 (이징 없음).
타임라인 중첩
타임라인은 다른 타임라인을 포함할 수 있습니다.
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");
재생 제어
- tl.play() / tl.pause()
- tl.reverse() / tl.progress(1) 후 tl.reverse()
- tl.restart() — 처음부터.
- tl.time(2) — 2초로 이동.
- tl.progress(0.5) — 50%로 이동.
- tl.kill() — 타임라인과 (기본적으로) 그 하위 요소들을 종료합니다.
공식 GSAP 모범 사례
- ✅ 시퀀싱에는 타임라인을 선호하세요
- ✅ 위치 파라미터 (세 번째 인수)를 사용하여 트윈을 특정 시간이나 레이블에 상대적으로 배치하세요.
- ✅
addLabel()로 레이블을 추가하여 가독성 좋고 유지보수 쉬운 시퀀스를 만드세요. - ✅ 기본값을 타임라인 생성자에 전달하여 하위 트윈이 duration, ease 등을 상속받게 하세요.
- ✅ ScrollTrigger는 타임라인(또는 최상위 트윈)에만 사용하고, 타임라인 내부의 트윈에는 사용하지 마세요.
하지 말아야 할 것
- ❌ 여러 단계 애니메이션에 delay로 연결하지 말고, 타임라인과 위치 파라미터를 사용하세요.
- ❌ 많은 하위 트윈이 동일한 duration이나 ease를 공유할 때 defaults (예:
defaults: { duration: 0.5, ease: "power2.out" })를 전달하는 것을 잊지 마세요. - ❌ 타임라인 생성자의 duration이 트윈 duration과 같지 않다는 것을 잊지 마세요; 타임라인의 "duration"은 하위 요소에 의해 결정됩니다.
- ❌ ScrollTrigger를 포함하는 애니메이션을 중첩하지 마세요; ScrollTrigger는 최상위 트윈/타임라인에만 있어야 합니다.