ARIA 항목에 액세스 가능한 이름이 없음

Available in: Español, Português, 中文, English
이 페이지에서

Users of screen readers and other assistive technologies need information about the behavior and purpose of controls on your web page. Built-in HTML controls like buttons and radio groups come with that information built in. For custom controls you create, however, you must provide the information with ARIA roles and attributes. (Learn more in the Introduction to ARIA.)

To be announced properly by assistive technologies, both built-in HTML controls and custom ARIA controls must have accessible names that convey their purpose.

Lighthouse가 접근 가능한 이름이 없는 ARIA 항목을 식별하는 방법 #

Lighthouse는 보조 기술에서 이름에 액세스할 수 없는 사용자 지정 ARIA 항목에 플래그를 지정합니다.

접근 가능한 이름이 없는 사용자 지정 토글 요소를 표시하는 Lighthouse 감사

액세스 가능한 이름을 확인하는 7개의 감사가 있으며 각 감사는 서로 다른 ARIA 역할 집합을 다룹니다. 다음 ARIA 역할 중 하나가 있지만 액세스 가능한 이름이 없는 요소로 인해 이 감사가 실패합니다.

감사 이름ARIA 역할
aria-command-namebutton , link , menuitem
aria-input-field-namecombobox , listbox , searchbox slider , spinbutton , textbox
aria-meter-namemeter
aria-progressbar-nameprogressbar
aria-toggle-field-namecheckbox , menu , menuitemcheckbox , menuitemradio , radio , radiogroup , switch
aria-tooltip-nametooltip
aria-treeitem-nametreeitem

예시 1: 사용자 지정 ARIA 토글 필드에 액세스 가능한 이름을 추가하는 방법 #

옵션 1: 요소에 내부 텍스트 추가 #

대부분의 요소에 액세스 가능한 이름을 제공하는 가장 쉬운 방법은 요소 내부에 텍스트 콘텐츠를 포함하는 것입니다.

예를 들어 이 사용자 지정 확인란은 보조 기술 사용자에게 "신문"으로 발표됩니다.

<div id="checkbox1" role="checkbox">Newspaper</div>

클립 패턴을 사용하면 화면에서 내부 텍스트를 숨길 수 있지만 여전히 보조 기술을 통해 알릴 수 있습니다. 이것은 현지화를 위해 페이지를 번역하는 경우 특히 유용할 수 있습니다.

<a href="/accessible">Learn more <span class="visually-hidden">about accessibility on web.dev</span></a>

옵션 2: 요소에 aria-label 속성 추가 #

내부 텍스트를 추가할 수 없는 경우(예: 요소의 이름을 표시하지 않으려는 경우) aria-label 속성을 사용하십시오.

이 사용자 지정 스위치는 보조 기술 사용자에게 "블루 라이트 전환"으로 발표됩니다.

<div id="switch1"
    role="switch"
    aria-checked="true"
    aria-label="Toggle blue light">
    <span>off</span>
    <span>on</span>
</div>

옵션 3: aria-labelledby를 사용하여 다른 요소 참조 #

aria-labelledby 속성을 사용하여 현재 요소의 이름으로 사용할 ID를 사용하여 다른 요소를 식별합니다.

예를 들어, 이 사용자 정의 메뉴 라디오 버튼은 menuitem1Label 단락을 레이블로 참조하며 "Sans-serif"로 발표됩니다.

<p id="menuitem1Label">Sans-serif</p>
<ul role="menu">
    <li id="menuitem1"
        role="menuitemradio"
        aria-labelledby="menuitem1Label"
        aria-checked="true"></li>
</ul>

예시 2: 사용자 지정 ARIA 입력 필드에 접근 가능한 이름을 추가하는 방법 #

대부분의 요소에 액세스 가능한 이름을 제공하는 가장 쉬운 방법은 요소에 텍스트 콘텐츠를 포함하는 것입니다. 그러나 사용자 지정 입력 필드에는 일반적으로 내부 텍스트가 없으므로 대신 다음 전략 중 하나를 사용할 수 있습니다.

옵션 1: 요소에 aria-label 속성 추가 #

aria-label 속성을 사용하여 현재 요소의 이름을 정의합니다.

예를 들어 이 사용자 지정 콤보 상자는 보조 기술 사용자에게 "국가"로 발표됩니다.

<div id="combo1" aria-label="country" role="combobox"></div>

옵션 2: aria-labelledby를 사용하여 다른 요소 참조 #

aria-labelledby 속성을 사용하여 현재 요소의 이름으로 사용할 ID를 사용하여 다른 요소를 식별합니다.

예를 들어 이 사용자 정의 검색 상자는 searchLabel 단락을 레이블로 참조하며 "검색 통화 쌍"으로 발표됩니다.

<p id="searchLabel">Search currency pairs:</p>
<div id="search"
    role="searchbox"
    contenteditable="true"
    aria-labelledby="searchLabel"></div>

리소스 #

접근성
마지막 업데이트: — 기사 개선하기
Return to all articles
공유