ARIA 접근성 가이드

속성 · 표·목록 구조

aria-colcount

표·그리드에 전체 열이 몇 개인지 알립니다. 일부 열만 DOM에 있을 때 씁니다.

심화

한눈에 보기

구분
속성 (Property)
분류
표·목록 구조
값 형식
정수 (integer), 전체 열 수 또는 -1
기본값
자동 계산
적용 범위
특정 역할에만 사용
HTML 대체
<table> (모든 열이 DOM에 있으면 브라우저가 자동 계산)

설명

aria-colcount는 table, grid, treegrid의 전체 열 개수를 알립니다. 표 컨테이너 요소에 붙입니다.

모든 열이 DOM에 있으면 브라우저가 열을 세어 자동으로 계산하므로 필요하지 않습니다. 열이 수십·수백 개인 스프레드시트형 그리드에서 화면에 보이는 열만 렌더링(가로 가상 스크롤)하는 경우에 씁니다. 이때 값을 넣지 않으면 화면낭독기는 "열 5개"처럼 렌더링된 개수만 안내합니다.

값은 전체 표의 열 수와 같은 정수여야 하며, 전체 개수를 모르면 -1을 넣어 브라우저가 계산하지 않도록 합니다(명세상 MUST). aria-colcount를 넣었다면 각 셀의 실제 위치를 알리는 aria-colindex도 함께 넣어야 의미가 있습니다.

네이티브 <table>에도 쓸 수 있지만, 모든 열이 그려진 일반 표라면 넣지 않습니다. 값이 실제와 다르면 오히려 표 탐색 정보가 틀어집니다.

검수할 때는 화면낭독기로 표에 진입했을 때 안내되는 열 수가 실제 전체 열 수와 같은지, 렌더링된 셀의 aria-colindex가 함께 제공되는지 확인합니다.

값

값
값의미
<정수>전체 표의 열 개수입니다.
-1전체 열 수를 알 수 없습니다. 브라우저가 계산하지 않습니다.
(생략) 기본값DOM에 있는 열을 세어 자동 계산합니다.

사용 예

16개 열 중 일부만 렌더링한 그리드

권장HTML
<div role="grid" aria-label="월별 실적" aria-colcount="16">
  <div role="row">
    <div role="columnheader" aria-colindex="2">1월</div>
    <div role="columnheader" aria-colindex="3">2월</div>
    <div role="columnheader" aria-colindex="4">3월</div>
    <div role="columnheader" aria-colindex="9">8월</div>
  </div>
</div>

가로 스크롤로 열이 바뀔 때

JavaScript
// 전체 열 수는 그대로, 렌더링한 셀의 aria-colindex만 다시 계산합니다.
grid.setAttribute('aria-colcount', String(columns.length));
visibleCells.forEach((cell) => {
  cell.setAttribute('aria-colindex', String(cell.dataset.col));
});

모든 열이 있는 일반 표

비권장HTML
<!-- 비권장: 자동 계산되므로 불필요하며, 값이 틀리면 정보가 왜곡됨 -->
<table aria-colcount="5">
  <tr><th>이름</th><th>부서</th><th>직급</th></tr>
</table>

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
aria-colcount="16" 그리드에 진입월별 실적, 그리드, 열 16개, 행 …개
속성 없이 4열만 렌더링된 경우월별 실적, 그리드, 열 4개

사용 지침

이렇게 쓰세요

  • 일부 열만 DOM에 렌더링할 때 표 컨테이너에 넣습니다.
  • 함께 각 셀(또는 행)에 aria-colindex를 넣습니다.
  • 전체 열 수를 모르면 -1을 씁니다.

이렇게 쓰지 마세요

  • 모든 열이 DOM에 있는 표에 넣지 않습니다.
  • 행이나 셀에 붙이지 않습니다. 표 컨테이너(table, grid, treegrid)에 붙입니다.
  • 실제 열 수와 다른 값을 넣지 않습니다.

사용할 수 있는 역할

tablegridtreegrid
aria-colindexaria-rowcountaria-colspan

이 속성을 쓰는 패턴

정렬 가능한 표

참고 자료