aria-posinset

설명

aria-posinset는 집합 안에서 항목의 위치(순번)를 1부터 세어 알립니다. 화면낭독기는 이 값과 aria-setsize를 합쳐 "50개 중 5번째"처럼 안내합니다. listitem, option, treeitem, menuitem(체크·라디오 메뉴 항목 포함), radio, tab, row(트리 그리드), article(피드) 등 집합의 구성원에 붙이며, 컨테이너에는 붙이지 않습니다.

모든 항목이 DOM에 있으면 필요 없습니다. 브라우저가 형제 요소를 세어 자동으로 계산하기 때문입니다. 필요한 경우는 가상 스크롤(보이는 부분만 렌더링), 무한 스크롤 피드, 페이지 단위로 불러오는 목록처럼 집합의 일부만 DOM에 있을 때입니다. 이때 값을 넣지 않으면 "50개 중 5번째"가 "4개 중 1번째"로 잘못 안내됩니다.

값은 1 이상이어야 하고, 전체 개수를 알면 aria-setsize 이하여야 합니다. 명세는 aria-posinset를 쓸 때 aria-setsize도 함께 쓰라고 권고합니다. 메뉴에서는 separator를 제외하고 셉니다. 트리처럼 계층이 있으면 같은 수준·같은 부모 안에서의 위치입니다.

자동 계산을 쓰지 않는 순간 값을 직접 관리해야 하므로, 항목을 추가·삭제·정렬할 때 모든 항목의 값을 다시 계산해야 합니다. 한 항목만 바꾸면 순번이 겹치거나 빠집니다.

검수할 때는 일부만 렌더링된 목록에서 화면낭독기가 전체 기준 위치를 읽는지, 스크롤로 항목이 바뀐 뒤에도 순번이 맞는지, 값이 1부터 시작하는지(0 사용 금지) 확인합니다.

값

사용 예

<ul aria-label="검색 결과">
  <li aria-setsize="16" aria-posinset="5">결과 5</li>
  <li aria-setsize="16" aria-posinset="6">결과 6</li>
  <li aria-setsize="16" aria-posinset="7">결과 7</li>
  <li aria-setsize="16" aria-posinset="8">결과 8</li>
</ul>

<div role="feed" aria-busy="false" aria-label="새 소식">
  <article aria-posinset="21" aria-setsize="-1" aria-labelledby="a21-title">
    <h2 id="a21-title">가을 할인 안내</h2>
  </article>
</div>

function renderWindow(list, items, start, total) {
  list.replaceChildren(...items.map((text, i) => {
    const li = document.createElement('li');
    li.textContent = text;
    li.setAttribute('aria-posinset', String(start + i)); // 전체 기준 위치
    li.setAttribute('aria-setsize', String(total));
    return li;
  }));
}

<!-- 비권장: 자동 계산되므로 불필요하고, 0부터 시작해 잘못됨 -->
<ul>
  <li aria-posinset="0">사과</li>
  <li aria-posinset="1">배</li>
</ul>

직접 해 보기

전체 50건 중 4건만 DOM에 그려지는 목록입니다. "다음 4건"을 누르면 항목이 바뀌고, 각 항목의 aria-posinset이 전체 기준 위치로 바뀝니다.

화면낭독기에서는

사용 지침

사용할 수 있는 역할

관련 속성·패턴

이 속성을 쓰는 패턴

참고 자료

• WAI-ARIA 1.2 명세: aria-posinset (새 창)
• APG: Feed 패턴 (새 창)
• APG: Tree View 패턴 (새 창)
• MDN: aria-posinset (새 창)