Progress

작업 진행도를 보여 주는 진행 막대이며, 끌 수 있는 손잡이를 붙일 수 있습니다.

이럴 때 쓰세요. 작업 진행도를 보여 줄 막대가 필요할 때. 읽기 전용 진행도에는 <r-progress>를 그대로 쓰고, 사용자가 손잡이를 끌어 값을 정해야 한다면 type="drag"를 쓰세요.

빠른 시작

<r-progress percent="40%"></r-progress>

💡 팁: r-progress는 고유 너비가 없는 블록 레벨 엘리먼트입니다. flex 행 안에서는 너비가 0으로 눌릴 수 있으니, 명시적 너비(예: style="width:100%")를 주거나 블록 맥락에 두세요.

API 레퍼런스

프로퍼티

프로퍼티	타입	기본값	설명
`percent`	`string`	`'0'`	현재 진행도. 숫자나 백분율을 받습니다. `total`이 상한입니다.
`total`	`string`	`'100'`	전체 진행량. 숫자나 백분율을 받습니다.
`type`	`string`	`'primary'`	막대 종류: `primary`(정적) 또는 `drag`(클릭·드래그 가능).
`dot`	`string`	`'true'`	드래그 손잡이를 보일지: `true` 또는 `false`.
`sheet`	`string`	`''`	컴포넌트의 섀도 DOM에 주입할 CSS.

진행 값 `percent`

현재 진행도를 지정합니다. 숫자나 백분율 문자열을 받으며 total을 넘을 수 없습니다. total을 지정하지 않으면 기본값이 100이므로, percent는 100에 대한 백분율로 읽힙니다.

<r-progress percent="30%"></r-progress>
<r-progress percent="70%"></r-progress>
<r-progress percent="100%"></r-progress>

전체 진행량 `total`

percent의 분모를 지정합니다. 숫자와 백분율 모두 쓸 수 있어서 percent="30" total="1000"이면 막대가 3% 찹니다.

<r-progress percent="30" total="1000"></r-progress>
<r-progress percent="70" total="100"></r-progress>
<r-progress percent="10%" total="100%"></r-progress>

막대 종류 `type`

primary: 정적 진행 막대. type을 지정하지 않았을 때의 기본값입니다.
drag: 클릭하고 끌 수 있는 진행 막대. 트랙을 클릭하거나 손잡이를 끌면 percent가 갱신되고 change 이벤트가 발생합니다. 손잡이를 끌려면 dot="true"가 필요합니다.

<r-progress type="drag" percent="30%"></r-progress> <r-progress type="primary" percent="40%"></r-progress>

드래그 손잡이 `dot`

손잡이 표시를 켜고 끕니다. 손잡이는 dot="true" 이면서 type="drag"일 때만 그려집니다. 정적인 primary 막대에서는 일부러 빼므로, 거기서는 dot이 눈에 보이는 효과를 내지 않습니다.

<r-progress type="drag" percent="30%" dot="true"></r-progress>
<r-progress type="drag" percent="30%" dot="false"></r-progress>

이벤트

`change`

drag 종류에서 사용자가 트랙을 클릭하거나 손잡이를 끌어 percent가 바뀔 때마다 디스패치됩니다. detail 객체가 담는 값은 다음과 같습니다.

필드	타입	설명
`value`	`string`	현재 진행도
`percent`	`string`	현재 진행도
`total`	`string`	전체 진행량

<r-progress type="drag" percent="30%"></r-progress>

<script>
  const progress = document.createElement('r-progress');
  progress.type = 'drag';
  progress.percent = '30%';
  progress.addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.percent, e.detail.total);
  });
  container.append(progress);
</script>

CSS Part

Part	설명
`track`	진행 트랙(배경).
`fill`	트랙에서 채워진 부분.
`dot`	드래그 손잡이.

r-progress::part(fill) {
  background: var(--ran-color-primary);
}

권장 사항

정적 막대: 읽기 전용 진행도에는 기본값 type="primary"를 쓰세요.
조작 가능한 막대: 사용자가 값을 정해야 한다면 type="drag"를 쓰고 change 이벤트를 구독하세요.
백분율과 숫자: percent와 total은 자유롭게 섞어 쓰세요. 알려진 전체량에 대응하는 원 숫자를 넘겨도 되고, 직접 제어하려면 백분율을 써도 됩니다.
레이아웃 너비: flex 레이아웃에서 눌리지 않도록 막대를 블록 컨테이너로 감싸거나 명시적 너비를 지정하세요.