Progress

Progress (프로그레스 바)

스택형 바, 애니메이션 배경, 텍스트 라벨을 지원하는 Bootstrap 커스텀 프로그레스 바의 문서와 예시를 다룹니다.

출처: 문서

본문

v5.3.0의 새 마크업 — 프로그레스 바의 기존 HTML 구조는 폐기(deprecated)되고 더 접근성 높은 구조로 교체되었습니다. 기존 구조는 v6까지 계속 동작합니다. 변경 사항은 마이그레이션 가이드에서 확인하세요.

동작 원리 (How it works)

프로그레스 컴포넌트는 두 개의 HTML 요소, 너비를 설정하는 약간의 CSS, 그리고 몇 가지 속성으로 만들어집니다. HTML5 <progress> 요소는 사용하지 않으므로 프로그레스 바를 스택하거나, 애니메이션하거나, 그 위에 텍스트 라벨을 놓을 수 있습니다.

• .progress를 프로그레스 바의 최대값을 나타내는 래퍼로 사용합니다.
• .progress 래퍼는 접근성을 위해 role="progressbar"와 aria 속성도 필요합니다. 여기에는 접근 가능한 이름(accessible name, aria-label, aria-labelledby 등을 사용)이 포함됩니다.
• 안쪽의 .progress-bar는 시각적 바와 라벨만을 위해 사용합니다.
• .progress-bar는 너비를 설정하기 위해 인라인 스타일, 유틸리티 클래스, 또는 커스텀 CSS가 필요합니다.
• 여러/스택형 프로그레스 바를 만들기 위해 특별한 .progress-stacked 클래스를 제공합니다.

이것들을 모두 합치면 다음과 같은 예시가 됩니다.

<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar" style="width: 0%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar" style="width: 25%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar" style="width: 50%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar" style="width: 75%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar" style="width: 100%"></div>
</div>

바 크기 (Bar sizing)

너비 (Width)

Bootstrap은 너비를 설정하는 몇 가지 유틸리티를 제공합니다. 필요에 따라 이것들로 .progress-bar의 너비를 빠르게 구성하는 데 도움을 받을 수 있습니다.

<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar w-75"></div>
</div>

높이 (Height)

.progress 컨테이너에만 height 값을 설정하면 됩니다. 이 값을 바꾸면 안쪽의 .progress-bar가 자동으로 그에 맞게 크기가 조절됩니다.

<div class="progress" role="progressbar" aria-label="Example 1px high" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100" style="height: 1px">
  <div class="progress-bar" style="width: 25%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Example 20px high" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100" style="height: 20px">
  <div class="progress-bar" style="width: 25%"></div>
</div>

라벨 (Labels)

.progress-bar 안에 텍스트를 넣으면 프로그레스 바에 라벨을 추가할 수 있습니다.

<div class="progress" role="progressbar" aria-label="Example with label" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar" style="width: 25%">25%</div>
</div>

긴 라벨 (Long labels)

기본적으로 .progress-bar 안의 콘텐츠는 overflow: hidden으로 제어되므로 바 밖으로 넘치지 않습니다. 프로그레스 바가 라벨보다 짧으면 콘텐츠가 잘려 읽기 어려워질 수 있습니다. 이 동작을 바꾸려면 overflow 유틸리티의 .overflow-visible을 사용할 수 있습니다.

프로그레스 바보다 긴 라벨은 이 방법으로 완전히 접근 가능하지 않을 수 있습니다. 텍스트 색상이 .progress와 .progress-bar 배경 색상 양쪽과 올바른 대비 비율을 가져야 하기 때문입니다. 이 예시를 구현할 때는 주의하세요.

텍스트가 프로그레스 바와 겹칠 수 있다면, 접근성을 위해 라벨을 프로그레스 바 밖에 표시하는 것을 자주 권장합니다.

배경 (Backgrounds)

개별 프로그레스 바의 모양을 바꾸려면 배경 유틸리티 클래스를 사용하세요.

<div class="progress" role="progressbar" aria-label="Success example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar bg-success" style="width: 25%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Info example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar bg-info" style="width: 50%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Warning example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar bg-warning" style="width: 75%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Danger example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar bg-danger" style="width: 100%"></div>
</div>

접근성 팁: 의미를 더하기 위해 색상을 사용하는 것은 시각적 표시일 뿐이며, 스크린 리더 같은 보조 기술 사용자에게는 전달되지 않습니다. 의미가 콘텐츠 자체(예: 충분한 색상 대비를 가진 보이는 텍스트)에서 분명하거나, .visually-hidden 클래스로 숨겨진 추가 텍스트 같은 대체 수단을 통해 포함되도록 해 주세요.

커스텀 배경 색상으로 프로그레스 바에 라벨을 추가한다면, 적절한 텍스트 색상도 설정해서 라벨이 읽기 쉽고 충분한 대비를 갖도록 해 주세요. color와 background 헬퍼 클래스를 사용하는 것을 권장합니다.

<div class="progress" role="progressbar" aria-label="Success example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar text-bg-success" style="width: 25%">25%</div>
</div>
<div class="progress" role="progressbar" aria-label="Info example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar text-bg-info" style="width: 50%">50%</div>
</div>
<div class="progress" role="progressbar" aria-label="Warning example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar text-bg-warning" style="width: 75%">75%</div>
</div>
<div class="progress" role="progressbar" aria-label="Danger example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar text-bg-danger" style="width: 100%">100%</div>
</div>

여러 개의 바 (Multiple bars)

.progress-stacked가 있는 컨테이너 안에 여러 프로그레스 컴포넌트를 넣어 하나의 스택형 프로그레스 바를 만들 수 있습니다. 이 경우에는 .progress-bar가 아니라 .progress 요소에 프로그레스 바의 시각적 너비를 설정하는 스타일을 적용해야 한다는 점에 주의하세요.

<div class="progress-stacked">
  <div class="progress" role="progressbar" aria-label="Segment one" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100" style="width: 15%">
    <div class="progress-bar"></div>
  </div>
  <div class="progress" role="progressbar" aria-label="Segment two" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100" style="width: 30%">
    <div class="progress-bar bg-success"></div>
  </div>
  <div class="progress" role="progressbar" aria-label="Segment three" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100" style="width: 20%">
    <div class="progress-bar bg-info"></div>
  </div>
</div>

줄무늬 (Striped)

.progress-bar에 .progress-bar-striped를 추가하면 CSS 그라디언트를 통해 프로그레스 바의 배경 색상 위에 줄무늬를 적용할 수 있습니다.

<div class="progress" role="progressbar" aria-label="Default striped example" aria-valuenow="10" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar progress-bar-striped" style="width: 10%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Success striped example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar progress-bar-striped bg-success" style="width: 25%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Info striped example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar progress-bar-striped bg-info" style="width: 50%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Warning striped example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar progress-bar-striped bg-warning" style="width: 75%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Danger striped example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar progress-bar-striped bg-danger" style="width: 100%"></div>
</div>

애니메이션 줄무늬 (Animated stripes)

줄무늬 그라디언트는 애니메이션할 수도 있습니다. .progress-bar에 .progress-bar-animated를 추가하면 CSS3 애니메이션으로 줄무늬를 오른쪽에서 왼쪽으로 움직일 수 있습니다.

<div class="progress" role="progressbar" aria-label="Animated striped example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
  <div class="progress-bar progress-bar-striped progress-bar-animated" style="width: 75%"></div>
</div>

CSS

변수 (Variables)

v5.2.0에서 추가됨

Bootstrap의 진화하는 CSS 변수 접근 방식의 일부로, 프로그레스 바는 이제 향상된 실시간 커스터마이즈를 위해 .progress에 로컬 CSS 변수를 사용합니다. CSS 변수의 값은 Sass로 설정되므로 Sass 커스터마이즈도 여전히 지원됩니다.

--#{$prefix}progress-height: #{$progress-height};
@include rfs($progress-font-size, --#{$prefix}progress-font-size);
--#{$prefix}progress-bg: #{$progress-bg};
--#{$prefix}progress-border-radius: #{$progress-border-radius};
--#{$prefix}progress-box-shadow: #{$progress-box-shadow};
--#{$prefix}progress-bar-color: #{$progress-bar-color};
--#{$prefix}progress-bar-bg: #{$progress-bar-bg};
--#{$prefix}progress-bar-transition: #{$progress-bar-transition};

Sass 변수

$progress-height:                   1rem;
$progress-font-size:                $font-size-base * .75;
$progress-bg:                       var(--#{$prefix}secondary-bg);
$progress-border-radius:            var(--#{$prefix}border-radius);
$progress-box-shadow:               var(--#{$prefix}box-shadow-inset);
$progress-bar-color:                $white;
$progress-bar-bg:                   $primary;
$progress-bar-animation-timing:     1s linear infinite;
$progress-bar-transition:           width .6s ease;

Keyframes

.progress-bar-animated의 CSS 애니메이션을 만드는 데 사용됩니다. scss/_progress-bar.scss에 포함되어 있습니다.

@if $enable-transitions {
  @keyframes progress-bar-stripes {
    0% { background-position-x: var(--#{$prefix}progress-height); }
  }
}

더 알아보기 (Learn more)

• Bootstrap 문서