ARIA 접근성 가이드

역할 · 위젯

role="progressbar"

오래 걸리는 작업의 진행 정도를 보여 주는 표시줄입니다. 진행률을 모르면 값을 생략해 “진행 중”만 알립니다.

기초HTML 요소 우선

한눈에 보기

분류
위젯
대응 HTML
<progress>
이름 정하는 방법
작성자
이름 필수
예
필수 상위 요소
없음
필수 하위 요소
없음

설명

progressbar는 파일 업로드, 설치, 여러 단계 처리처럼 시간이 걸리는 작업의 진행 상황을 나타냅니다. 사용자가 조작하는 요소가 아니라 읽기 전용 표시이므로 포커스를 받지 않습니다.

  • 확정형(determinate) — aria-valuenow에 현재 값을 넣습니다. aria-valuemin·aria-valuemax의 기본값은 0과 100입니다. 백분율이 아닌 표현(“3개 중 2개 완료”)이 더 알맞으면 aria-valuetext를 씁니다.
  • 불확정형(indeterminate) — 진행률을 모르면 aria-valuenow를 빼야 합니다. 화면낭독기는 값 없이 “진행 표시줄”만 알립니다.

WAI-ARIA 1.2에서 이름은 필수입니다(aria-label 또는 aria-labelledby). 무엇의 진행률인지 알 수 있어야 합니다. HTML <progress>는 같은 역할을 가지며 <label>로 이름을 붙일 수 있습니다.

값이 바뀐다고 자동으로 읽어 주지 않습니다

대부분의 화면낭독기는 포커스가 없는 진행 표시줄의 값 변화를 알리지 않거나, 알리더라도 일관되지 않습니다. 시작·완료처럼 중요한 순간은 status 같은 라이브 리전으로 따로 알립니다. 진행 표시줄이 갱신 중인 영역을 설명한다면 그 영역에 aria-busy="true"를, aria-describedby로 영역과 진행 표시줄을 연결할 수 있습니다.

측정값(배터리 잔량, 디스크 사용량)처럼 작업 진행이 아닌 고정된 수치는 meter(HTML <meter>)를 씁니다.

테스터 관점

  • 진행 표시줄에 이름이 있는지, 값(또는 값 텍스트)이 화면 표시와 일치하는지 확인합니다.
  • 불확정 상태에서 aria-valuenow="0" 같은 잘못된 값이 남아 있지 않은지 확인합니다.
  • 작업 완료가 라이브 리전 등으로 알려지는지 확인합니다.

함께 쓰는 속성

지원 속성

aria-valuemaxaria-valueminaria-valuenowaria-valuetext

전역 속성(이름·설명 등)은 모든 역할에 쓸 수 있어 생략했습니다.

사용 예

네이티브 progress

권장권장
<label for="up">사진 업로드</label>
<progress id="up" max="100" value="40">40%</progress>

ARIA 진행 표시줄 (확정형 + 값 텍스트)

HTML
<div role="progressbar" aria-label="설치 진행률"
     aria-valuenow="2" aria-valuemin="0" aria-valuemax="3"
     aria-valuetext="3단계 중 2단계: 파일 복사 중">
  <div class="bar" style="width: 66%"></div>
</div>

불확정형

aria-valuenow를 넣지 않습니다.

HTML
<div role="progressbar" aria-label="목록 불러오는 중"></div>

값 갱신

JavaScript
function setProgress(bar, value) {
  bar.setAttribute('aria-valuenow', String(value));
  bar.firstElementChild.style.width = value + '%';
  if (value >= 100) status.textContent = '업로드가 완료되었습니다.';
}

직접 해 보기

“업로드 시작”을 누르면 진행 표시줄 값이 올라가고, 완료되면 상태 메시지가 라이브 리전으로 알려집니다. “불확정 상태”를 누르면 aria-valuenow가 제거되는 모습을 실시간 코드에서 볼 수 있습니다.

사진 업로드

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
가상 커서로 진행 표시줄에 도달사진 업로드, 진행 표시줄, 40%
값 텍스트가 있는 경우설치 진행률, 진행 표시줄, 3단계 중 2단계: 파일 복사 중
불확정형목록 불러오는 중, 진행 표시줄

사용 지침

이렇게 쓰세요

  • 가능하면 <progress>를 쓰고 이름을 붙입니다.
  • 진행률을 모르면 aria-valuenow를 제거합니다.
  • 시작·완료·실패는 라이브 리전으로 따로 알립니다.

이렇게 쓰지 마세요

  • 진행 표시줄에 tabindex를 주어 포커스를 받게 하지 않습니다. 조작 요소가 아닙니다.
  • 고정된 측정값(용량, 점수)에 쓰지 않습니다. meter를 씁니다.
  • 값을 아주 짧은 간격으로 바꾸면서 라이브 리전으로 매번 읽히게 하지 않습니다.
meterstatussliderscrollbar

이 역할을 쓰는 패턴

알림 메시지(토스트·상태)

참고 자료