aria-valuenow

설명

aria-valuenow는 범위 위젯의 현재 값입니다. slider, meter, scrollbar, 포커스를 받을 수 있는 separator에서는 필수 속성이고, spinbutton과 progressbar에서는 선택 속성입니다. 값은 aria-valuemin 이상 aria-valuemax 이하의 숫자여야 하며, 소수도 쓸 수 있습니다.

이름에 "now"가 들어 있지만 명세상 분류는 상태(state)가 아니라 속성(property)입니다. 그래도 실제로는 가장 자주 바뀌는 값이므로, 키보드·마우스·터치 등 어떤 방법으로 값을 바꾸든 스크립트가 즉시 이 속성을 갱신해야 합니다. 화면 속 손잡이만 움직이고 속성을 그대로 두면 화면낭독기는 계속 처음 값을 읽습니다.

보조기술은 역할에 따라 값을 다르게 읽습니다. 명세는 progressbar와 scrollbar는 최솟값·최댓값 사이의 위치를 백분율로, slider와 spinbutton은 실제 값으로 안내하도록 권고합니다. 숫자만으로 뜻이 전달되지 않으면(예: 요일, "작게/보통/크게") aria-valuetext로 읽을 문장을 따로 줍니다.

값을 알 수 없을 때는 aria-valuenow를 넣지 않습니다. 예를 들어 전체 크기를 모르는 작업의 진행 표시줄은 aria-valuenow를 생략해 "불확정(indeterminate)" 상태로 둡니다. 0이나 임의의 숫자를 넣으면 "0%"처럼 잘못된 정보가 전달됩니다.

검수할 때는 방향키·Page Up/Down·Home/End·마우스 드래그로 값을 바꾼 뒤 실시간 코드나 접근성 트리에서 값이 함께 바뀌는지, 화면에 보이는 숫자와 일치하는지, 범위를 벗어나지 않는지 확인합니다. 화면낭독기로는 값이 바뀔 때마다 새 값이 읽히는지 들어 봅니다.

값

사용 예

<span id="vol-label">음량</span>
<div id="vol" role="slider" tabindex="0"
     aria-labelledby="vol-label"
     aria-valuemin="0" aria-valuemax="10" aria-valuenow="5">
  <span class="thumb"></span>
</div>

const slider = document.getElementById('vol');
slider.addEventListener('keydown', (e) => {
  let v = Number(slider.getAttribute('aria-valuenow'));
  if (e.key === 'ArrowRight' || e.key === 'ArrowUp') v += 1;
  else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') v -= 1;
  else if (e.key === 'Home') v = 0;
  else if (e.key === 'End') v = 10;
  else return;
  e.preventDefault();
  v = Math.min(10, Math.max(0, v));
  slider.setAttribute('aria-valuenow', String(v)); // 화면과 속성을 함께 바꿉니다
  moveThumb(v);
});

<!-- 진행률을 아는 경우 -->
<div role="progressbar" aria-label="설치 진행률"
     aria-valuemin="0" aria-valuemax="100" aria-valuenow="40"></div>

<!-- 진행률을 모르는 경우: aria-valuenow를 넣지 않습니다 -->
<div role="progressbar" aria-label="서버 응답 대기 중"></div>

<!-- 비권장: 손잡이는 8로 움직였지만 속성은 처음 값 그대로 -->
<div role="slider" tabindex="0" aria-label="음량"
     aria-valuemin="0" aria-valuemax="10" aria-valuenow="5">
  <span class="thumb" style="left: 80%"></span>
</div>

직접 해 보기

슬라이더에 포커스를 두고 방향키, Page Up / Page Down, Home / End를 눌러 보세요. 실시간 코드에서 aria-valuenow가 바뀌는 것을 볼 수 있습니다.

화면낭독기에서는

사용 지침

사용할 수 있는 역할

관련 속성·패턴

이 속성을 쓰는 패턴

참고 자료

• WAI-ARIA 1.2 명세: aria-valuenow (새 창)
• APG: Slider 패턴 (새 창)
• APG: Spinbutton 패턴 (새 창)
• APG: Meter 패턴 (새 창)
• MDN: aria-valuenow (새 창)