GSAP
HyperFrames 계약
HyperFrames는 gsap 런타임 어댑터를 통해 GSAP를 제어합니다. 동기식으로 일시 중지된 타임라인을 생성하고, 정확한 data-composition-id로 window.__timelines에 등록한 후, HyperFrames가 이를 탐색(seek)하도록 합니다.
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
window.__timelines["main"] = tl; // 키는 컴포지션 루트의 data-composition-id와 일치해야 합니다.
</script>
- 레지스트리 키는 컴포지션 루트의
data-composition-id와 일치해야 합니다. - 렌더링에 중요한 모션을 위해
tl.play()를 호출하지 마세요. - 비동기 코드, 타이머 또는 이벤트 핸들러 내부에서 타임라인을 생성하지 마세요.
- 루프는 유한하게 유지하세요. HyperFrames는 유한한 비디오 길이를 렌더링합니다.
핵심 트윈 메서드
- gsap.to(targets, vars) — 현재 상태에서
vars까지 애니메이션합니다. 가장 일반적입니다. - gsap.from(targets, vars) —
vars부터 현재 상태까지 애니메이션합니다 (등장). - gsap.fromTo(targets, fromVars, toVars) — 명시적인 시작 및 종료.
- gsap.set(targets, vars) — 즉시 적용합니다 (지속 시간 0).
항상 camelCase 속성 이름을 사용하세요 (예: backgroundColor, rotationX).
공통 vars
- duration — 초 (기본값 0.5).
- delay — 시작 전 지연 시간(초).
- ease —
"power1.out"(기본값),"power3.inOut","back.out(1.7)","elastic.out(1, 0.3)","none". - stagger — 숫자
0.1또는 객체:{ amount: 0.3, from: "center" },{ each: 0.1, from: "random" }. - overwrite —
false(기본값),true, 또는"auto". - repeat — 유한한 숫자; HyperFrames에서 절대
-1을 사용하지 마세요. 보이는 지속 시간에서 반복 횟수를 계산하세요. yoyo — repeat과 함께 방향을 번갈아 바꿉니다. - onComplete, onStart, onUpdate — 콜백.
- immediateRender — from()/fromTo()의 기본값은
true입니다. 동일한 속성+요소를 대상으로 하는 이후 트윈에서는false로 설정하여 덮어쓰기를 방지하세요.
변환 및 CSS
원시 transform 문자열보다 GSAP의 transform 별칭을 선호하세요:
| GSAP 속성 | 동등 표현 |
|---|---|
x, y, z | translateX/Y/Z (px) |
xPercent, yPercent | translateX/Y (%) |
scale, scaleX, scaleY | scale |
rotation | rotate (deg) |
rotationX, rotationY | 3D rotate |
skewX, skewY | skew |
transformOrigin | transform-origin |
- autoAlpha —
opacity보다 선호하세요. 0일 때: 또한visibility: hidden을 설정합니다. - CSS 변수 —
"--hue": 180. - svgOrigin (SVG 전용) — 전역 SVG 좌표 공간 원점.
transformOrigin과 함께 사용하지 마세요. - 방향성 회전 —
"360_cw","-170_short","90_ccw". - clearProps —
"all"또는 쉼표로 구분; 완료 시 인라인 스타일을 제거합니다. - 상대 값 —
"+=20","-=10","*=2".
함수 기반 값
gsap.to(".item", {
x: (i, target, targets) => i * 50,
stagger: 0.1,
});
easing
내장 easing: power1–power4, back, bounce, circ, elastic, expo, sine. 각각 .in, .out, .inOut 접미사를 가집니다.
기본값
gsap.defaults({ duration: 0.6, ease: "power2.out" });
트윈 제어
const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);
gsap.matchMedia() (반응형 + 접근성)
미디어 쿼리가 일치할 때만 설정을 실행하고, 일치하지 않을 때 자동으로 되돌립니다.
let mm = gsap.matchMedia();
mm.add(
{
isDesktop: "(min-width: 800px)",
reduceMotion: "(prefers-reduced-motion: reduce)",
},
(context) => {
const { isDesktop, reduceMotion } = context.conditions;
gsap.to(".box", {
rotation: isDesktop ? 360 : 180,
duration: reduceMotion ? 0 : 2,
});
},
);
타임라인
타임라인 생성
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
위치 매개변수
세 번째 인수는 배치를 제어합니다:
- 절대:
1— 1초 지점 - 상대:
"+=0.5"— 끝 이후;"-=0.2"— 끝 이전 - 레이블:
"intro","intro+=0.3" - 정렬:
"<"— 이전 트윈과 동시 시작;">"— 이전 트윈 종료 후;"<0.2"— 이전 트윈 시작 후 0.2초
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // .a와 동시 시작
tl.to(".c", { opacity: 0 }, "<0.2"); // .b 시작 후 0.2초
레이블
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");
타임라인 옵션
- paused: true — 일시 중지된 상태로 생성;
.play()를 호출하여 시작합니다. - repeat, yoyo — 전체 타임라인에 적용됩니다.
- defaults — 모든 하위 트윈에 병합되는 vars입니다.
타임라인 중첩
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
재생 제어
tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().
성능
변환 및 불투명도 선호
x, y, scale, rotation, opacity 애니메이션은 컴포지터에서 유지됩니다. transforms로 동일한 효과를 얻을 수 있다면 width, height, top, left 사용을 피하세요.
will-change
will-change: transform;
실제로 애니메이션되는 요소에만 적용하세요.
빈번한 업데이트를 위한 gsap.quickTo()
let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
xTo(e.pageX);
yTo(e.pageY);
});
여러 개의 트윈 대신 Stagger 사용
개별 지연 시간이 있는 여러 트윈 대신 stagger를 사용하세요.
정리
화면 밖 애니메이션은 일시 중지하거나 제거(kill)하세요.
참조 (요청 시 로드됨)
- references/effects.md — 즉시 사용 가능한 효과: 타자기 텍스트, 오디오 시각화 도구. HyperFrames를 위한 기성 효과 패턴이 필요할 때 읽으세요.
모범 사례
- camelCase 속성 이름을 사용하고, transform 별칭과 autoAlpha를 선호하세요.
- delay로 체이닝하는 것보다 타임라인을 선호하고 위치 매개변수를 사용하세요.
- 가독성 있는 시퀀싱을 위해
addLabel()로 레이블을 추가하세요. - 타임라인 생성자에 defaults를 전달하세요.
- 재생 제어가 필요할 때는 트윈/타임라인의 반환 값을 저장하세요.
하지 말아야 할 것
- transforms로 충분할 때 레이아웃 속성(width/height/top/left)을 애니메이션하지 마세요.
- 동일한 SVG 요소에 svgOrigin과 transformOrigin을 함께 사용하지 마세요.
- 타임라인이 시퀀싱할 수 있을 때 delay로 애니메이션을 체이닝하지 마세요.
- DOM이 존재하기 전에 트윈을 생성하지 마세요.
- 정리를 건너뛰지 마세요 — 더 이상 필요하지 않은 트윈은 항상 제거(kill)하세요.
- HyperFrames 컴포지션에서 무한 반복 값을 사용하지 마세요. 보이는 지속 시간에서 계산된 유한한 반복 횟수를 사용하세요.
크레딧 및 참조
- HyperFrames 어댑터 소스:
packages/core/src/runtime/adapters/gsap.ts. - GSAP 문서: https://gsap.com/docs/v3/
- GSAP 타임라인 일시 중지 및 탐색 동작: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/