Progress#

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

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 Progress(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: Progress(value: 0.65),
    );
  }
}

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

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

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

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

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

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

class _ProgressRadialExampleState extends State<ProgressRadialExample> {
  @override
  Component build(BuildContext context) {
    return RadialProgress(
      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 RadialProgress(
      value: 75,
      showValueText: true,
    );
  }
}

사용 시기 (When to Use)#

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

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

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

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

기본 사용법 (Basic Usage)#

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

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

// 색상/두께 커스터마이징은 progressStyle 슬롯으로
Progress(
  value: 0.5,
  progressStyle: CoreProgressStyle(
    color: CoreColor.token(CoreColors.tertiary),
    minHeight: 12,
  ),
)

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

// 원형 크기/두께 커스터마이징
RadialProgress(
  value: 50,
  radialProgressStyle: CoreRadialProgressStyle(size: 120, strokeWidth: 12),
)

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

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

// 색상/두께 커스터마이징은 progressStyle 슬롯으로
Progress(
  value: 0.5,
  progressStyle: CoreProgressStyle(
    color: CoreColor.token(CoreColors.tertiary),
    minHeight: 12,
  ),
)

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

Props / Parameters#

Per Epic #1302 / Phase 6f 모든 chrome / dimensional override는 단일 Style 슬롯 (progressStyle / radialProgressStyle) 한 곳으로 모입니다. 위젯 평면 파라미터는 behaviour (value / min / max / disableAnimation / showValueText / child) 만 남습니다.

Progress (직선형)#

CoreProgressStyle 필드 (chrome)

RadialProgress (원형)#

CoreRadialProgressStyle 필드 (chrome)

동작 스펙 (Behavior)#

직선형#

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

원형#

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

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

Do#

RadialProgress(
  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는 읽기 전용)