NumberTicker#

숫자가 부드럽게 보간되며 변경되는 애니메이션 효과를 가진 숫자 표시 컴포넌트입니다. 통계, 카운터, 대시보드 수치 표시에 적합합니다.

Live Preview#

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

  @override
  State<NumberTickerDefaultExample> createState() =>
      _NumberTickerDefaultExampleState();
}

class _NumberTickerDefaultExampleState
    extends State<NumberTickerDefaultExample> {
  @override
  Component build(BuildContext context) {
    return NumberTicker(value: 1234, initialValue: 0);
  }
}

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

  @override
  State<NumberTickerDefaultExample> createState() =>
      _NumberTickerDefaultExampleState();
}

class _NumberTickerDefaultExampleState
    extends State<NumberTickerDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return NumberTicker(
      value: 1234,
      initialValue: 0,
    );
  }
}

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

  @override
  State<NumberTickerChainExample> createState() => _NumberTickerChainExampleState();
}

class _NumberTickerChainExampleState extends State<NumberTickerChainExample> {
  @override
  Component build(BuildContext context) {
    return NumberTicker(value: 1234, initialValue: 0).withStyle(
      const CoreNumberTickerStyle(
        duration: Duration(milliseconds: CoreDuration.slow),
        textStyle: CoreTextStyle.token(
          CoreTextStyles.headlineSmall,
          color: CoreColor.token(CoreColors.primary),
        ),
      ),
    );
  }
}

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

  @override
  State<NumberTickerChainExample> createState() => _NumberTickerChainExampleState();
}

class _NumberTickerChainExampleState extends State<NumberTickerChainExample> {
  @override
  Widget build(BuildContext context) {
    return NumberTicker(
      value: 1234,
      initialValue: 0,
    ).withStyle(
      const CoreNumberTickerStyle(
        duration: Duration(milliseconds: CoreDuration.slow),
        textStyle: CoreTextStyle.token(
          CoreTextStyles.headlineSmall,
          color: CoreColor.token(CoreColors.primary),
        ),
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 대시보드에서 실시간으로 변하는 수치를 시각적으로 강조하고 싶을 때
• 랜딩 페이지에서 사용자 수, 매출 등 인상적인 통계 수치를 애니메이션으로 표시할 때
• 게임이나 포인트 시스템에서 점수 변화를 생동감 있게 표현할 때

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

• Countdown: 남은 시간을 초 단위로 표시할 때
• Progress: 완료율이나 진행률을 바 형태로 표시할 때
• Text: 단순 숫자 표시로 충분하고 애니메이션이 필요 없을 때

기본 사용법 (Basic Usage)#

// 기본 숫자 틱커
NumberTicker(value: 1234)

// 커스텀 포맷터 (통화)
NumberTicker(
  value: 98765,
  formatter: (n) => '\$${n.toStringAsFixed(2)}',
  numberTickerStyle: CoreNumberTickerStyle(
    duration: Duration(milliseconds: 800),
  ),
)

// 커스텀 빌더 (완전한 표시 제어)
NumberTicker.builder(
  value: score,
  builder: (context, value, child) {
    return Text('${value.toInt()} points').headlineSmall.onSurface;
  },
)

// 기본 숫자 틱커
NumberTicker(value: 1234)

// 커스텀 포맷터 (통화)
NumberTicker(
  value: 98765,
  formatter: (n) => '\$${n.toStringAsFixed(2)}',
  numberTickerStyle: CoreNumberTickerStyle(
    duration: Duration(milliseconds: 800),
  ),
)

// 커스텀 빌더 (완전한 표시 제어)
NumberTicker.builder(
  value: score,
  builder: (context, value, child) {
    return Text('${value.toInt()} points').headlineSmall.onSurface;
  },
)

빠른 오버라이드 (Chain)#

이미 만든 NumberTicker 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

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

  @override
  State<NumberTickerChainExample> createState() => _NumberTickerChainExampleState();
}

class _NumberTickerChainExampleState extends State<NumberTickerChainExample> {
  @override
  Widget build(BuildContext context) {
    return NumberTicker(
      value: 1234,
      initialValue: 0,
    ).withStyle(
      const CoreNumberTickerStyle(
        duration: Duration(milliseconds: CoreDuration.slow),
        textStyle: CoreTextStyle.token(
          CoreTextStyles.headlineSmall,
          color: CoreColor.token(CoreColors.primary),
        ),
      ),
    );
  }
}

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

  @override
  State<NumberTickerChainExample> createState() => _NumberTickerChainExampleState();
}

class _NumberTickerChainExampleState extends State<NumberTickerChainExample> {
  @override
  Component build(BuildContext context) {
    return NumberTicker(value: 1234, initialValue: 0).withStyle(
      const CoreNumberTickerStyle(
        duration: Duration(milliseconds: CoreDuration.slow),
        textStyle: CoreTextStyle.token(
          CoreTextStyles.headlineSmall,
          color: CoreColor.token(CoreColors.primary),
        ),
      ),
    );
  }
}

Props / Parameters#

NumberTicker는 두 생성자를 갖습니다 — 포맷된 텍스트를 그리는 기본 생성자와, 표시를 완전히 제어하는 NumberTicker.builder. 두 표시 경로는 상호 배타적이라 formatter는 기본 생성자에만, builder / child는 .builder에만 있습니다.

NumberTicker (기본 생성자)#

NumberTicker.builder#

CoreNumberTickerStyle 필드#

동작 스펙 (Behavior)#

애니메이션#

• value가 변경되면 이전 값에서 새 값으로 부드럽게 보간
• 기본 500ms ease-in-out 커브
• 애니메이션 중 새 값이 들어오면 현재 값에서 새 값으로 전환

사용 가이드라인 (Usage Guidelines)#

Do#

NumberTicker(
  value: revenue,
  formatter: (n) => '\$${n.toStringAsFixed(0)}',
)

Don't#

접근성 (Accessibility)#

스크린 리더#

• Flutter: Semantics 위젯으로 현재 값 설명 제공 권장
• Web: aria-live="polite"로 값 변경 알림

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

관련 컴포넌트 (Related Components)#

• Stat: 라벨과 함께 통계 수치를 표시
• Countdown: 시간 기반 카운트다운
• Progress: 진행률 시각화