타이머

countdown-timer는 특정 종료 시점까지 남은 시간을 실시간으로 표시해주는 웹 컴포넌트입니다. 서버 시간을 기준으로 동작하여 사용자의 로컬 시간 설정에 영향을 받지 않습니다.

기본 사용법

<script type="module">
  if (!window.customElements.get("countdown-timer")) {
    import("/ui/element/countdown-timer.js");
  }
</script>

<countdown-timer
  start="20240301120000"
  end="20240308120000"
  class="v-countdown-timer"
>
  <div data-timer class="active">
    <span data-timer-hours>23</span>
    :
    <span data-timer-minutes>59</span>
    :
    <span data-timer-seconds>51</span>
  </div>
</countdown-timer>

실제 모습

00 : 00 : 00

필수 속성 (Attributes)

속성	타입	설명
start	String	서버 시간 기준점 (YYYYMMDDHHMMSS 형식)
end	String	카운트다운 종료 시간 (YYYYMMDDHHMMSS 형식)

선택 속성

속성	타입	기본값	설명
enable-visibility-change	Boolean	true	탭 이동 감지 기능 활성화 여부
pad	Boolean | JSON	true	숫자를 두 자리로 표시할지 여부
active-class	String	"active"	활성화 시 추가할 클래스 이름
ended-class	String	"ended"	타이머 종료 시 추가할 클래스 이름

마크업 구조 및 표시 형식

타이머는 두 가지 표시 형식을 지원합니다:

1. 일/시/분/초 형식

data-timer-days 요소가 포함된 경우 사용됩니다:

<countdown-timer>
  <div data-timer>
    <span data-timer-days>00</span>일 <span data-timer-hours>00</span>시간
    <span data-timer-minutes>00</span>분 <span data-timer-seconds>00</span>초
  </div>
</countdown-timer>

2. 시/분/초 형식 (일을 시간으로 통합)

data-timer-days 요소가 없는 경우 자동으로 일을 시간으로 변환하여 표시합니다:

<countdown-timer>
  <div data-timer>
    <span data-timer-hours>00</span>시간 <span data-timer-minutes>00</span>분
    <span data-timer-seconds>00</span>초
  </div>
</countdown-timer>

예를 들어, 남은 시간이 1일 5시간이라면:

• 일/시/분/초 형식: 1일 5시간
• 시/분/초 형식: 29시간 (1일 = 24시간으로 변환)

각 요소는 모두 선택적으로 사용할 수 있습니다. 필요한 부분만 마크업에 포함시키세요.

고급 설정 예제

특정 시간 단위만 패딩(0 채우기) 적용

<countdown-timer
  start="20240301120000"
  end="20240308120000"
  pad='{"days": false, "hours": true, "minutes": true, "seconds": true}'
>
  <!-- 타이머 내용 -->
</countdown-timer>

커스텀 클래스 지정

<countdown-timer
  start="20240301120000"
  end="20240308120000"
  active-class="is-counting"
  ended-class="is-finished"
>
  <!-- 타이머 내용 -->
</countdown-timer>

상태 클래스

타이머는 다음과 같은 상태에 따라 컨테이너 요소에 클래스를 추가합니다:

• active: 타이머가 활성화되어 카운트다운 중일 때
• ended: 타이머가 종료되었을 때