GSAP 애니메이션 모범 사례
GSAP(GreenSock Animation Platform)을 사용하여 전문적이고 접근 가능하며 성능이 뛰어난 애니메이션을 구현하기 위한 종합 가이드입니다.
핵심 원칙
1. 성능 우선
transform과opacity만 애니메이션 처리 (GPU 가속)width,height,top,left,margin,padding애니메이션 지양will-change는 신중하게 사용- 모든 기기에서 60fps 목표
2. 항상 접근성 고려
prefers-reduced-motion존중- JavaScript 없이도 콘텐츠가 표시되도록 보장
- 중요한 콘텐츠를 애니메이션 뒤에 숨기지 않음
- 긴 애니메이션에는 건너뛰기/일시 중지 컨트롤 제공
3. 점진적 향상
- 콘텐츠는 애니메이션 없이도 작동해야 함
- 애니메이션은 기능을 향상시킬 뿐 대체하지 않음
- 애니메이션이 비활성화된 상태에서 테스트
GSAP 설정
설치
<!-- CDN (WordPress 권장) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>
<!-- 선택적 플러그인 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollSmoother.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/SplitText.min.js"></script>
WordPress Enqueue
function theme_enqueue_gsap() {
// GSAP Core
wp_enqueue_script(
'gsap',
'https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js',
array(),
'3.12.5',
true
);
// ScrollTrigger
wp_enqueue_script(
'gsap-scrolltrigger',
'https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js',
array('gsap'),
'3.12.5',
true
);
// 테마 애니메이션
wp_enqueue_script(
'theme-animations',
get_theme_file_uri('/assets/js/animations.js'),
array('gsap', 'gsap-scrolltrigger'),
filemtime(get_theme_file_path('/assets/js/animations.js')),
true
);
}
add_action('wp_enqueue_scripts', 'theme_enqueue_gsap');
애니메이션 패턴
1. 스크롤 시 페이드 인
// 기본 페이드 인
gsap.from('.fade-in', {
opacity: 0,
y: 50,
duration: 1,
stagger: 0.2,
scrollTrigger: {
trigger: '.fade-in',
start: 'top 80%',
toggleActions: 'play none none none'
}
});
2. 엇갈린 요소
// 카드가 하나씩 나타남
gsap.from('.card', {
opacity: 0,
y: 100,
duration: 0.8,
stagger: {
amount: 0.6,
from: 'start'
},
ease: 'power2.out',
scrollTrigger: {
trigger: '.cards-container',
start: 'top 75%'
}
});
3. 패럴랙스 효과
// 이미지에 미묘한 패럴랙스 적용
gsap.to('.parallax-image', {
yPercent: -20,
ease: 'none',
scrollTrigger: {
trigger: '.parallax-section',
start: 'top bottom',
end: 'bottom top',
scrub: true
}
});
4. 텍스트 공개 (줄 단위)
// SplitText 플러그인 필요 (Club GreenSock)
// 또는 아래 CSS 기반 대안 사용
// CSS 대안 - 각 줄을 span으로 감싸기
gsap.from('.reveal-line', {
opacity: 0,
y: '100%',
duration: 0.8,
stagger: 0.1,
ease: 'power3.out',
scrollTrigger: {
trigger: '.text-reveal',
start: 'top 80%'
}
});
5. 커튼/마스크 공개
// 슬라이딩 마스크로 이미지 공개
gsap.to('.curtain-mask', {
scaleX: 0,
transformOrigin: 'right center',
duration: 1.2,
ease: 'power4.inOut',
scrollTrigger: {
trigger: '.curtain-container',
start: 'top 70%'
}
});
6. 영웅 애니메이션 타임라인
// 복잡한 영웅 시퀀스
const heroTL = gsap.timeline({
defaults: { ease: 'power3.out' }
});
heroTL
.from('.hero-bg', { scale: 1.2, duration: 1.5 })
.from('.hero-title', { opacity: 0, y: 100, duration: 1 }, '-=1')
.from('.hero-subtitle', { opacity: 0, y: 50, duration: 0.8 }, '-=0.5')
.from('.hero-cta', { opacity: 0, y: 30, duration: 0.6 }, '-=0.3');
접근성
축소된 동작 존중
// 사용자 기본 설정 확인
const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
// 옵션 1: 모든 애니메이션 비활성화
if (prefersReducedMotion) {
gsap.globalTimeline.timeScale(0);
ScrollTrigger.getAll().forEach(st => st.kill());
}
// 옵션 2: 단순화된 애니메이션
const animationConfig = prefersReducedMotion
? { duration: 0, stagger: 0 }
: { duration: 1, stagger: 0.2 };
gsap.from('.element', {
opacity: 0,
y: prefersReducedMotion ? 0 : 50,
...animationConfig
});
CSS 대비책
/* JavaScript 없이도 콘텐츠가 표시되도록 보장 */
.fade-in {
opacity: 1;
transform: translateY(0);
}
/* 애니메이션이 실행될 경우에만 숨기기 */
.js .fade-in {
opacity: 0;
transform: translateY(50px);
}
/* CSS에서도 축소된 동작 존중 */
@media (prefers-reduced-motion: reduce) {
.js .fade-in {
opacity: 1;
transform: none;
}
}
HTML에 JS 클래스 추가
// 스크립트 시작 부분에 추가
document.documentElement.classList.add('js');
반응형 애니메이션
중단점 인식 애니메이션
// 반응형 애니메이션 생성
const mm = gsap.matchMedia();
mm.add('(min-width: 1024px)', () => {
// 데스크톱 애니메이션
gsap.from('.hero-image', {
x: 100,
opacity: 0,
duration: 1.2
});
return () => {
// 중단점 변경 시 정리
};
});
mm.add('(max-width: 1023px)', () => {
// 모바일 애니메이션 (더 간단하게)
gsap.from('.hero-image', {
opacity: 0,
duration: 0.8
});
});
크기 조정 시 새로 고침
// 크기 조정 시 ScrollTrigger 다시 계산
let resizeTimer;
window.addEventListener('resize', () => {
clearTimeout(resizeTimer);
resizeTimer = setTimeout(() => {
ScrollTrigger.refresh();
}, 250);
});
성능 최적화
1. Transform 속성만 사용
// 좋음 - GPU 가속
gsap.to('.element', {
x: 100, // transform: translateX
y: 50, // transform: translateY
rotation: 45, // transform: rotate
scale: 1.2, // transform: scale
opacity: 0.5
});
// 나쁨 - 레이아웃/페인트 유발
gsap.to('.element', {
left: 100, // 레이아웃 트리거
width: '200px', // 레이아웃 트리거
marginTop: 50 // 레이아웃 트리거
});
2. 유사한 애니메이션 일괄 처리
// 많은 유사 요소에 batch 사용
ScrollTrigger.batch('.card', {
onEnter: batch => gsap.to(batch, {
opacity: 1,
y: 0,
stagger: 0.1
}),
start: 'top 85%'
});
3. 사용하지 않는 ScrollTrigger 제거
// SPA 탐색 또는 컴포넌트 언마운트 시 정리
function cleanup() {
ScrollTrigger.getAll().forEach(st => st.kill());
gsap.killTweensOf('*');
}
4. 지연 초기화
// 표시되는 섹션에 대해서만 애니메이션 초기화
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
initSectionAnimations(entry.target);
observer.unobserve(entry.target);
}
});
}, { rootMargin: '100px' });
document.querySelectorAll('.animated-section').forEach(section => {
observer.observe(section);
});
ScrollTrigger 모범 사례
1. 적절한 시작/종료 지점
// 일반적인 실수 방지
ScrollTrigger.create({
trigger: '.section',
start: 'top 80%', // 트리거 상단이 뷰포트 상단에서 80% 지점에 도달했을 때
end: 'bottom 20%', // 트리거 하단이 상단에서 20% 지점에 도달했을 때
markers: true, // 디버깅 전용 - 프로덕션에서는 제거!
});
2. 섹션 고정 시 주의
// 고정은 레이아웃 문제를 일으킬 수 있음
ScrollTrigger.create({
trigger: '.pinned-section',
start: 'top top',
end: '+=100%',
pin: true,
pinSpacing: true, // 일반적으로 true 유지
anticipatePin: 1 // 모바일에 도움
});
3. 이미지 로딩 처리
// 위치 계산 전에 이미지 로딩 대기
ScrollTrigger.config({
ignoreMobileResize: true
});
window.addEventListener('load', () => {
ScrollTrigger.refresh();
});
// 또는 지연 로딩 이미지 후 새로 고침
document.querySelectorAll('img[loading="lazy"]').forEach(img => {
img.addEventListener('load', () => ScrollTrigger.refresh());
});
테스트 통합
시각적 QA 호환성
시각적 QA 기술이 애니메이션을 올바르게 캡처하려면:
// 모든 애니메이션을 즉시 완료하는 함수 노출
window.completeAllAnimations = function() {
gsap.globalTimeline.progress(1);
ScrollTrigger.getAll().forEach(st => {
st.scroll(st.end);
});
};
// 또는 스크린샷을 위해 애니메이션을 완전히 건너뛰기
if (window.location.search.includes('skip-animations')) {
gsap.globalTimeline.timeScale(100);
}
Playwright 테스팅
// Playwright 테스트에서
await page.evaluate(() => {
if (window.completeAllAnimations) {
window.completeAllAnimations();
}
});
await page.waitForTimeout(500);
await page.screenshot({ path: 'screenshot.png', fullPage: true });
공통 애니메이션 라이브러리
재사용 가능한 애니메이션 클래스
// animations.js - 재사용 가능한 애니메이션 라이브러리
const Animations = {
// 모든 애니메이션 초기화
init() {
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
return;
}
this.fadeIn();
this.slideIn();
this.parallax();
this.textReveal();
},
fadeIn() {
gsap.utils.toArray('[data-animate="fade-in"]').forEach(el => {
gsap.from(el, {
opacity: 0,
y: 50,
duration: 0.8,
scrollTrigger: {
trigger: el,
start: 'top 85%',
once: true
}
});
});
},
slideIn() {
gsap.utils.toArray('[data-animate="slide-left"]').forEach(el => {
gsap.from(el, {
opacity: 0,
x: -100,
duration: 1,
scrollTrigger: {
trigger: el,
start: 'top 80%',
once: true
}
});
});
gsap.utils.toArray('[data-animate="slide-right"]').forEach(el => {
gsap.from(el, {
opacity: 0,
x: 100,
duration: 1,
scrollTrigger: {
trigger: el,
start: 'top 80%',
once: true
}
});
});
},
parallax() {
gsap.utils.toArray('[data-parallax]').forEach(el => {
const speed = el.dataset.parallax || 0.2;
gsap.to(el, {
yPercent: -100 * speed,
ease: 'none',
scrollTrigger: {
trigger: el.parentElement,
start: 'top bottom',
end: 'bottom top',
scrub: true
}
});
});
},
textReveal() {
gsap.utils.toArray('[data-animate="text-reveal"]').forEach(el => {
const lines = el.querySelectorAll('.line');
gsap.from(lines, {
opacity: 0,
y: '100%',
duration: 0.8,
stagger: 0.1,
scrollTrigger: {
trigger: el,
start: 'top 80%',
once: true
}
});
});
},
// 동적 콘텐츠 후 새로 고침
refresh() {
ScrollTrigger.refresh();
},
// SPA 탐색을 위한 정리
destroy() {
ScrollTrigger.getAll().forEach(st => st.kill());
gsap.killTweensOf('*');
}
};
// DOM 준비 시 초기화
document.addEventListener('DOMContentLoaded', () => Animations.init());
HTML 사용법
<!-- 페이드 인 -->
<div data-animate="fade-in">콘텐츠</div>
<!-- 왼쪽에서 슬라이드 -->
<div data-animate="slide-left">콘텐츠</div>
<!-- 패럴랙스 (0.2 = 20% 속도) -->
<img data-parallax="0.3" src="image.jpg">
<!-- 텍스트 공개 (줄 바꿈 필요) -->
<div data-animate="text-reveal">
<div class="line">첫 번째 줄</div>
<div class="line">두 번째 줄</div>
</div>
디버깅
마커 활성화
ScrollTrigger.defaults({
markers: true // 시작/종료 마커 표시
});
애니메이션 이벤트 로깅
gsap.to('.element', {
x: 100,
onStart: () => console.log('애니메이션 시작'),
onComplete: () => console.log('애니메이션 완료'),
onUpdate: self => console.log('진행률:', self.progress())
});
문제 확인
// 모든 ScrollTrigger 나열
console.log('ScrollTriggers:', ScrollTrigger.getAll());
// 요소 존재 여부 확인
const el = document.querySelector('.animated-element');
if (!el) console.warn('애니메이션 대상을 찾을 수 없습니다!');
체크리스트
출시 전
- 모든
markers: true제거 -
prefers-reduced-motion: reduce로 테스트 - 모바일 기기에서 테스트 (DevTools가 아닌 실제 기기)
- DevTools Performance 탭에서 성능 확인
- 대상 기기에서 60fps 확인
- JavaScript 없이도 콘텐츠 표시 확인
- ScrollTrigger 새로 고침 전 이미지 지연 로딩 확인
- 레이아웃 쓰레싱 없음 (레이아웃 속성 애니메이션 방지)
시각적 QA 통합
- 스크린샷 전 애니메이션 완료
- 전체 페이지 스크롤이 모든 애니메이션 트리거
- 스크린샷이 최종 애니메이션 상태 캡처
- 모든 뷰포트 크기에서 테스트
