Countdown#

숫자 값(0-99)을 표시하는 디스플레이 컴포넌트입니다. 값이 변경될 때 전환 애니메이션이 적용됩니다. 타이머 로직은 부모 컴포넌트에서 관리합니다.

Live Preview#

class CountdownDefaultExample extends StatefulComponent {
  const CountdownDefaultExample({super.key});

  @override
  State<CountdownDefaultExample> createState() =>
      _CountdownDefaultExampleState();
}

class _CountdownDefaultExampleState extends State<CountdownDefaultExample> {
  @override
  Component build(BuildContext context) {
    return Countdown(value: 42);
  }
}

class CountdownDefaultExample extends StatefulWidget {
  const CountdownDefaultExample({super.key});

  @override
  State<CountdownDefaultExample> createState() =>
      _CountdownDefaultExampleState();
}

class _CountdownDefaultExampleState extends State<CountdownDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return const Countdown(value: 42);
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 카운트다운 숫자를 크게 표시할 때
• 시간 단위별 숫자를 개별 표시할 때 (시:분:초 각각)
• 세션 타임아웃 등 남은 시간을 숫자로 표시할 때

대신 다른 컴포넌트를 사용하세요:

• NumberTicker: 일반적인 숫자 애니메이션이 필요할 때
• Progress: 남은 시간을 비율로 시각화할 때

기본 사용법 (Basic Usage)#

// 기본 카운트다운
Countdown(value: 42)

// 크기 조절
Countdown(
  value: 42,
  countdownStyle: CoreCountdownStyle(fontSize: 64),
)

// 시:분:초 조합
Row(
  children: [
    Countdown(value: hours),
    Text(':'),
    Countdown(value: minutes),
    Text(':'),
    Countdown(value: seconds),
  ],
)

// 기본 카운트다운
Countdown(value: 42)

// 크기 조절
Countdown(
  value: 42,
  countdownStyle: CoreCountdownStyle(fontSize: 64),
)

// 시:분:초 조합
div([
  Countdown(value: hours),
  span([text(':')]),
  Countdown(value: minutes),
  span([text(':')]),
  Countdown(value: seconds),
], classes: 'flex items-center gap-1')

Props / Parameters#

스타일 시스템 (Style System)#

Epic #1302 nested Style API. 모든 chrome / 애니메이션 override 는 countdownStyle 슬롯 하나로 흐릅니다.

Resolve chain#

design system default
  → CoreCountdownTheme (legacy flat fields)
  → CoreCountdownTheme.style                      // 프로젝트 공통
  → parent component slot override
  → widget.countdownStyle                         // 인스턴스별

동작 스펙 (Behavior)#

인터랙션#

• Countdown은 표시 전용 컴포넌트입니다. 인터랙션 없음.
• 부모 컴포넌트에서 Timer로 value를 업데이트해야 합니다.

애니메이션#

• Flutter: AnimatedSwitcher + FadeTransition으로 값 변경 시 페이드 전환
• Web: CSS transition-opacity + CoreDuration.normal(200ms)로 값 변경 시 페이드 전환

접근성 (Accessibility)#

스크린 리더#

• Flutter: Semantics(liveRegion: true)로 값 변경 알림
• Web: aria-live="polite" + aria-label로 값 변경 알림

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• NumberTicker: 일반 숫자 카운터 애니메이션
• Stat: 레이블 + 값 형식의 통계 표시