animation-range-end 사용 시 흔한 문제와 해결을 위한 대체 코드 예시

animation-range-end는 scroll-timeline과 함께 사용될 때, 애니메이션의 진행이 끝나는 스크롤 컨테이너 또는 요소 내에서의 위치를 정의합니다.

/* 키워드 */
animation-range-end: normal; /* 기본값 */
animation-range-end: entry;
animation-range-end: exit;
animation-range-end: cover;
animation-range-end: contain;

/* <length> 값 (예: 100px) */
animation-range-end: 500px;

/* <percentage> 값 (예: 50%) */
animation-range-end: 50%;

/* 키워드 + <length> 또는 <percentage> */
animation-range-end: entry 100px;
animation-range-end: contain 10%;

설명

키워드는 애니메이션 대상 요소의 경계(edge)를 기준으로 스크롤 컨테이너의 어디에 도달했을 때 끝낼지를 정의합니다.

entry
대상 요소의 진입 경계 (일반적으로 하단)가 스크롤 컨테이너의 뷰포트에 들어오는 지점.

exit
대상 요소의 퇴장 경계 (일반적으로 상단)가 뷰포트에서 나가는 지점.

cover
대상 요소가 스크롤 컨테이너를 완전히 덮는 상태.

contain
대상 요소가 스크롤 컨테이너에 완전히 포함되는 상태.

오프셋 값 (<length> 또는 <percentage>)은 해당 키워드 위치에서 애니메이션을 얼마나 더 진행하거나 일찍 끝낼지를 조정합니다.

스크롤 기반 애니메이션을 설정할 때 자주 마주치는 문제점과 그에 대한 해결 방법을 알려드릴게요.

사용자가 의도한 애니메이션 종료 지점과 실제 스크롤 위치가 일치하지 않는 경우입니다.

잘못된 키워드 선택
entry와 exit 같은 키워드가 대상 요소의 크기에 따라 다르게 해석되어 의도한 것과 다른 시점에 끝날 수 있습니다.

오프셋 값의 오류
오프셋 값을 잘못 설정하여 애니메이션의 범위가 너무 짧거나 길어진 경우입니다.

animation-range-end에 오프셋 값을 추가하여 종료 지점을 미세하게 조정합니다.

샘플 코드 (조정 예시)

/* 문제가 있는 코드: 너무 일찍 끝남 */
.animate-item-early {
  animation-range-end: entry; /* 대상 요소 하단이 뷰포트에 들어오는 순간 끝 */
}

/* 대체 코드: 뷰포트의 50%를 더 스크롤해야 끝남 */
.animate-item-adjusted {
  animation-range-end: entry 50vh; /* 'entry' 지점으로부터 뷰포트 높이의 50%만큼 더 스크롤해야 끝 */
  /* 또는: 대상 요소가 완전히 포함될 때 끝내기 */
  /* animation-range-end: contain; */
}

스크롤 기반 애니메이션에서는 어떤 요소가 스크롤을 감지하는지 (scroll-timeline의 source)가 매우 중요합니다.

scroll-timeline의 source를 기본값 (뷰포트)으로 두고, 실제로는 특정 div 안의 스크롤에 반응하길 기대하는 경우입니다.

특정 요소의 스크롤을 타임라인으로 사용하려면, 그 요소에 scroll-timeline-name을 설정하고, 애니메이션 대상 요소에서 animation-timeline으로 정확히 참조해야 합니다.

샘플 코드 (대체 방법)

<div class="scrolling-container"> <div class="content">
    <div class="animated-box"></div> </div>
</div>

/* 1. 스크롤 컨테이너에 timeline 이름 지정 */
.scrolling-container {
  overflow-y: scroll;
  height: 300px;
  scroll-timeline-name: --box-scroll; /* 타임라인 이름 정의 */
}

/* 2. 애니메이션 대상 요소 */
.animated-box {
  animation: fade-out 1s linear;
  /* 3. 정의된 타임라인 사용 */
  animation-timeline: --box-scroll; 
  /* 4. 'box-scroll' 타임라인에서 애니메이션 끝 지점 정의 */
  animation-range-end: entry 200px; 
}

/* @keyframes는 일반적인 방식으로 정의 */
@keyframes fade-out {
  0% { opacity: 1; }
  100% { opacity: 0; }
}

animation-range-end는 시작 범위를 지정하는 animation-range-start와 함께 사용될 때, 애니메이션의 정확한 구간을 설정하는 데 가장 강력한 힘을 발휘합니다.

샘플 코드 (구간 지정)

요소가 뷰포트에 진입을 시작할 때 (Start)부터 뷰포트의 중앙을 지나서 (End)까지 텍스트가 왼쪽에서 오른쪽으로 이동하는 애니메이션을 만들어 봅시다.

.reveal-text {
  animation-name: slide-in;
  animation-duration: 1s; /* timeline을 사용할 때는 duration이 무의미하지만 문법상 필요 */
  animation-fill-mode: forwards;
  
  /* 1. 애니메이션 시작 지점: 대상 요소 하단이 뷰포트에 'entry' 될 때 (시작) */
  animation-range-start: entry; 
  
  /* 2. 애니메이션 끝 지점: 대상 요소 하단이 뷰포트 중앙 (50%)에 도달할 때 (종료) */
  /* 'entry' 키워드는 대상 요소의 하단을, 50%는 뷰포트의 50% 지점을 의미 */
  animation-range-end: entry 50%; 
  
  /* timeline을 지정하지 않으면 기본적으로 뷰포트 스크롤에 반응 */
}

@keyframes slide-in {
  0% {
    transform: translateX(-100%);
    opacity: 0;
  }
  100% {
    transform: translateX(0);
    opacity: 1;
  }
}

이처럼 animation-range-end를 사용하면 스크롤 진행률을 0%에서 100%까지의 특정 스크롤 구간에 매핑할 수 있어, 훨씬 동적이고 제어 가능한 애니메이션을 만들 수 있답니다.