Progress#

작업 진행률을 시각적으로 표시하는 컴포넌트입니다. 직선형(CoProgress)과 원형(CoRadialProgress)을 지원합니다.

Live Preview#

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

  @override
  State<ProgressDefaultExample> createState() => _ProgressDefaultExampleState();
}

class _ProgressDefaultExampleState extends State<ProgressDefaultExample> {
  @override
  Component build(BuildContext context) {
    return CoProgress(value: 0.65);
  }
}

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

  @override
  State<ProgressDefaultExample> createState() => _ProgressDefaultExampleState();
}

class _ProgressDefaultExampleState extends State<ProgressDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: double.infinity,
      child: CoProgress(value: 0.65),
    );
  }
}

class ProgressIndeterminateExample extends StatelessComponent {
  const ProgressIndeterminateExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoProgress();
  }
}

class ProgressIndeterminateExample extends StatelessWidget {
  const ProgressIndeterminateExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: double.infinity,
      child: CoProgress(),
    );
  }
}

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

  @override
  State<ProgressRadialExample> createState() => _ProgressRadialExampleState();
}

class _ProgressRadialExampleState extends State<ProgressRadialExample> {
  @override
  Component build(BuildContext context) {
    return CoRadialProgress(
      value: 75,
      showValueText: true,
    );
  }
}

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

  @override
  State<ProgressRadialExample> createState() => _ProgressRadialExampleState();
}

class _ProgressRadialExampleState extends State<ProgressRadialExample> {
  @override
  Widget build(BuildContext context) {
    return const CoRadialProgress(
      value: 75,
      showValueText: true,
    );
  }
}

사용 시기 (When to Use)#

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

• 파일 업로드, 다운로드 등 작업 진행률을 표시할 때
• 목표 달성률, 스토리지 사용량 등 비율을 시각화할 때

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

• Loading: 단순 로딩 스피너가 필요할 때
• Skeleton: 콘텐츠 로딩 플레이스홀더가 필요할 때
• Slider: 사용자가 값을 조절해야 할 때

기본 사용법 (Basic Usage)#

// 기본 진행률 바 (0.0 ~ 1.0 범위)
CoProgress(value: 0.65)

// 커스텀 min/max 범위 지정
CoProgress(value: 75, min: 0, max: 100)

// 색상 커스터마이징
CoProgress(
  value: 0.5,
  color: Colors.green,
  backgroundColor: Colors.green.withOpacity(0.2),
)

// 원형 진행률
CoRadialProgress(
  value: 75,
  showValueText: true,
)

// 기본 진행률 바 (0.0 ~ 1.0 범위)
CoProgress(value: 0.65)

// 커스텀 min/max 범위 지정
CoProgress(value: 75, min: 0, max: 100)

// 원형 진행률
CoRadialProgress(
  value: 75,
  showValueText: true,
)

Props / Parameters#

CoProgress (직선형)#

CoRadialProgress (원형)#

동작 스펙 (Behavior)#

직선형#

• value 변경 시 부드러운 width 애니메이션 (300ms ease-in-out)
• 인디케이터에 borderRadius 적용 — 양쪽 둥근 모양
• 트랙 배경 기본값: primary 색상의 20% 투명도

원형#

• 12시 방향(-π/2)에서 시작하는 원형 아크
• strokeCap: round — 양쪽 끝 둥근 형태
• showValueText: true 시 중앙에 "75%" 형태 표시

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

Do#

CoRadialProgress(
  value: 75,
  showValueText: true,
)

Don't#

접근성 (Accessibility)#

ARIA 속성#

• Web: role="progressbar", aria-valuenow, aria-valuemin, aria-valuemax 자동 적용
• Flutter: Semantics 노드에 진행률 값 전달

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

관련 컴포넌트 (Related Components)#

• Loading: 로딩 스피너
• Skeleton: 콘텐츠 플레이스홀더
• Slider: 값 조절 (Progress는 읽기 전용)