Scroll motion
모션은 구조를 설명해야 합니다: 무엇이 새로운지, 무엇이 함께 속하는지, 다음에 무엇을 봐야 하는지. 이러한 기능을 수행하지 않는 애니메이션은 단순한 장식에 불과하며 성능을 저하시킵니다. 따라서 아래 각 효과는 특정 목적에 연결되어 있습니다.
설정
<script defer src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/lenis@1/dist/lenis.min.js"></script>
<script defer src="/js/main.js"></script>
defer는 스크립트가 첫 페인트를 차단하지 않도록 하면서도 순서대로 실행되도록 하여, main.js(아래 코드)가 gsap을 볼 수 있게 합니다. 프로덕션에서는 정확한 버전([email protected])을 지정하거나 파일을 직접 호스팅하세요.
gsap.registerPlugin(ScrollTrigger);
const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
if (!reduce) {
const lenis = new Lenis({ duration: 1.1, smoothWheel: true });
lenis.on("scroll", ScrollTrigger.update);
gsap.ticker.add((t) => lenis.raf(t * 1000));
gsap.ticker.lagSmoothing(0);
}
모든 애니메이션을 if (!reduce)로 감싸거나 gsap.matchMedia()를 사용하세요. 전정 장애가 있는 사용자는 이유가 있어 해당 환경 설정을 지정한 것이며, 콘텐츠는 모션 없이도 완전히 볼 수 있어야 합니다.
효과 선택하기
| 목적 | 효과 | 참조 섹션 |
|---|---|---|
| 새 섹션 알림 | 마스크된 헤드라인 리빌 | Reveals |
| 항목들이 함께 속함을 표시 | 지연된 페이드 업 | Reveals |
| 이미지에 깊이 추가 | 패럴랙스, clip-path 리빌 | Images |
| 순서 전달 | 고정 단계, 선 그리기 | Pinning |
| 작업 범위 표시 | 가로 스크롤 | Pinning |
| 숫자 강조 | 카운트 업 | Details |
| 초기 로딩 커버 | 프리로더 | Details |
각 효과에 대한 바로 사용 가능한 코드는 references/snippets.md에 있습니다. 효과를 구현하려고 할 때 이 파일을 읽으세요. 계획 단계에서는 필요하지 않습니다.
규칙
transform과opacity만 애니메이션 처리하세요.top,width,margin또는box-shadow를 애니메이션 처리하면 매 프레임마다 레이아웃 또는 페인트가 트리거되어 중간 수준의 휴대폰에서 버벅거립니다.- 지속 시간: 리빌은 0.6
1.0초, 호버는 0.20.3초. 더 길면 두 번째 방문 시 느리게 느껴집니다. - 이징: 진입에는
power3.out, 전환에는power2.inOut, 스크러브 애니메이션에는none(스크러브가 이징을 제공합니다). - 스태거: 0.06~0.12초. 총 시간을 제한하세요: 카드가 12개인 경우 처음 6개만 스태거하고 나머지는 함께 처리합니다.
- 한 번만 재생하세요.
once: true또는toggleActions: "play none none none"을 사용하세요. 다시 스크롤할 때마다 애니메이션을 다시 실행하면 지루합니다. - 페이지당 하나의 쇼피스. 고정 또는 가로 섹션은 한 번은 기억에 남지만 세 번 사용하면 지치게 됩니다.
- 초기 상태는 JS로 설정하고 CSS로 설정하지 마세요. 스크립트 로드에 실패하면 CSS로 숨겨진 콘텐츠는 영원히 숨겨진 상태로 남습니다.
- 레이아웃 변경 후 새로고침: 폰트와 이미지가 로드된 후
ScrollTrigger.refresh()를 호출하지 않으면 트리거 위치가 어긋납니다.
window.addEventListener("load", () => ScrollTrigger.refresh());
document.fonts?.ready.then(() => ScrollTrigger.refresh());
모바일
gsap.matchMedia()를 사용하여 768px 미만에서 고정 및 가로 스크롤을 비활성화하고 콘텐츠를 일반적으로 쌓습니다.- Lenis의 터치 부드러운 스크롤은 종종 네이티브 모멘텀과 충돌합니다. 사용자가 요청하지 않는 한 터치 스크롤은 네이티브(기본값)로 유지하세요.
- 작은 화면에서는 패럴랙스 거리를 절반으로 줄이세요.
디버깅
- ScrollTrigger에
markers: true를 추가하여 시작 및 끝 라인을 확인하세요. - 고정 시작 시 점프가 발생하면 일반적으로 고정된 요소에 변환 부모가 있거나 높이가 변경되기 때문입니다.
- 애니메이션이 너무 일찍 실행됨: 위에 있는 이미지가 늦게 로드된 것입니다. 이미지에 명시적인
width와height를 설정하세요. - 아무것도 애니메이션되지 않음: 플러그인이 등록되었는지, 선택자가 일치하는지 확인하세요.
GSAP 없이
작은 사이트에서 간단한 페이드 업의 경우, 클래스를 추가하는 IntersectionObserver와 CSS 트랜지션으로 충분하며 약 70KB를 절약할 수 있습니다. references/snippets.md의 마지막 섹션을 참조하세요.