Progress Spinner

Progress Spinner는 진행 상태를 원형 애니메이션으로 표시하는 컴포넌트입니다. 로딩 상태를 표시하거나 특정 작업의 진행률을 시각적으로 나타낼 때 사용합니다.

기본 사용법

<template>
    <ProgressSpinner />
</template>

<script setup lang="ts">
import { ProgressSpinner } from '@jennifersoft/vue-components-v2';
</script>

진행률 표시하기

progressRatio 속성을 사용하여 0부터 1 사이의 값으로 진행률을 표시할 수 있습니다:

<template>
    <ProgressSpinner :progressRatio="0.75" />
</template>

위 예제는 원형의 75%가 채워진 상태를 보여줍니다.

속성 (Props)

속성	타입	기본값	설명
progressRatio	number	0	진행률을 나타내는 값 (0 ~ 1 사이)
color	string	var(--overlay-primary-900)	진행 표시기의 색상
circleColor	string	var(--overlay-primary-100)	배경 원의 색상
duration	string	1.5s	애니메이션 지속 시간
size	string	medium	컴포넌트 크기 (small, medium, large)

크기 옵션

Progress Spinner는 세 가지 크기를 지원합니다:

• small: 24px
• medium: 32px (기본값)
• large: 48px

<template>
    <ProgressSpinner size="small" />
    <ProgressSpinner />
    <!-- medium -->
    <ProgressSpinner size="large" />
</template>

색상 변경하기

기본 색상을 변경하려면 color와 circleColor 속성을 사용합니다:

<template>
    <ProgressSpinner
        color="var(--primary-700)"
        circleColor="var(--overlay-200)"
    />
</template>

동작 원리

Progress Spinner는 SVG 요소를 사용하여 원형 진행률을 표시합니다. stroke-dasharray와 stroke-dashoffset 속성을 활용하여 원의 일부분만 표시함으로써 진행률을 시각화합니다.

진행률은 다음과 같이 계산됩니다:

1. 원의 둘레(circumference)를 계산합니다: 2 * π * 반지름
2. progressRatio 값(0~1)에 따라 stroke-dasharray 속성을 설정합니다
3. 이를 통해 원의 특정 부분만 표시되도록 합니다

예제: 로딩 상태와 진행률 표시

<template>
    <div>
        <!-- 로딩 스피너 -->
        <div>
            <h3>로딩 중: {{ Math.round(autoProgress * 100) }}%</h3>
            <ProgressSpinner :progressRatio="autoProgress" />
        </div>

        <!-- 진행률 표시 -->
        <div>
            <h3>다운로드 진행률: {{ Math.round(progress * 100) }}%</h3>
            <ProgressSpinner :progressRatio="progress" />
        </div>
    </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { ProgressSpinner } from '@clara/vue-components';

const progress = ref(0.35); // 35% 진행 고정값
const autoProgress = ref(0); // 자동 진행률
let timer = null;

// 랜덤하게 진행률 증가 함수
const increaseProgress = () => {
    // 랜덤하게 1~5% 증가
    autoProgress.value += Math.random() * 0.05;
    
    // 100%를 넘으면 다시 0으로 리셋
    if (autoProgress.value >= 1) {
        autoProgress.value = 0;
    }
};

onMounted(() => {
    // 100ms마다 진행률 업데이트
    timer = setInterval(increaseProgress, 100);
});

onUnmounted(() => {
    // 컴포넌트 해제 시 타이머 정리
    clearInterval(timer);
});
</script>

예제: 현재 상태

아래는 이 페이지의 모든 예시 스피너들의 현재 진행률을 한눈에 보여줍니다:

기본: 0%

작은: 0%

중간: 0%

큰: 0%

색상: 0%

고정값: 75%

접근성

Progress Spinner 컴포넌트는 role="progressbar" 속성을 포함하여 스크린 리더 등의 접근성 도구에서 적절하게 인식됩니다.