ARIA 접근성 가이드

속성 · 위젯 상태 · 전역

aria-keyshortcuts

요소를 실행하거나 포커스하는 키보드 단축키가 있다는 것을 알립니다. 단축키 동작은 따로 구현해야 합니다.

중급

한눈에 보기

구분
속성 (Property)
분류
위젯 상태
값 형식
문자열 (공백으로 구분한 단축키 목록, 각 단축키는 <code>+</code>로 연결)
기본값
없음
적용 범위
모든 요소 (전역 속성)
HTML 대체
accesskey 속성 (브라우저마다 조합 키가 달라 권장하지 않음)

설명

aria-keyshortcuts는 페이지가 제공하는 단축키를 보조기술에 알려 주는 속성입니다. 예를 들어 “메모 추가” 버튼에 aria-keyshortcuts="Alt+Shift+M"을 붙이면, 화면낭독기는 버튼을 읽을 때 단축키도 함께 알려 줍니다. 속성은 정보 제공만 하므로, 실제 단축키 처리는 keydown 이벤트로 직접 구현해야 합니다.

값 형식은 명세에 정해져 있습니다. 한 단축키는 수정 키(Alt, Control, Shift, Meta)를 먼저, 일반 키를 마지막에 두고 +로 연결합니다. 키 이름은 UI Events의 KeyboardEvent.key 값을 씁니다(예: Delete, ArrowDown, 스페이스는 Space, 더하기 기호는 Plus). 여러 단축키는 공백으로 구분합니다. 예: aria-keyshortcuts="Control+Alt+P Meta+Alt+P". 또한 Shift를 눌러야 입력되는 기호는 그 기호와 Shift를 함께 적어야 합니다.

단축키를 만들 때는 충돌에 특히 주의합니다. 화면낭독기는 Insert·CapsLock·한 글자 키(H로 제목 이동 등)를 많이 쓰고, 브라우저와 운영체제도 많은 조합을 씁니다. 수정 키 없는 한 글자 단축키는 화면낭독기·음성 인식 사용자에게 큰 문제를 일으킬 수 있어 WCAG 2.1.4(문자 키 단축키)는 이를 끄거나 바꿀 수 있게 하거나, 해당 요소에 포커스가 있을 때만 동작하게 하도록 요구합니다.

모든 사용자가 단축키를 알 수 있도록 화면에도 단축키를 표시(툴팁, 메뉴 항목 옆 표시, 도움말 페이지)하는 것이 좋습니다. 화면에 보이는 단축키 텍스트가 버튼 이름에 들어가면 화면낭독기가 두 번 읽으므로, 표시 텍스트는 aria-hidden="true"로 숨기고 이 속성으로 전달할 수 있습니다.

테스트할 때는 값의 키 이름과 순서가 명세 형식을 따르는지, 실제 단축키가 동작하는지, 화면낭독기 켠 상태에서도 충돌 없이 동작하는지 확인합니다. 화면낭독기에 따라 이 속성을 읽지 않거나, 요소 정보 확인 명령에서만 알려 주기도 합니다.

값

값
값의미
단축키 문자열수정 키와 일반 키를 +로 연결한 단축키입니다. 예: Control+S, Alt+Shift+M.
여러 단축키 (공백 구분)같은 동작의 단축키가 여러 개일 때 공백으로 나열합니다. 예: Control+P Meta+P.

사용 예

단축키가 있는 버튼

권장HTML
<button type="button" aria-keyshortcuts="Alt+Shift+M">
  메모 추가 <kbd aria-hidden="true">Alt+Shift+M</kbd>
</button>

단축키 동작 구현

JavaScript
document.addEventListener('keydown', function (e) {
  // e.code를 쓰면 한글 입력 상태에서도 같은 물리 키로 인식합니다.
  if (e.altKey && e.shiftKey && !e.ctrlKey && !e.metaKey && e.code === 'KeyM') {
    e.preventDefault();
    addMemo();
  }
});

여러 플랫폼 단축키

HTML
<button type="button" aria-keyshortcuts="Control+Shift+F Meta+Shift+F">검색 패널 열기</button>

잘못된 형식과 한 글자 단축키 (비권장)

비권장HTML
<button type="button" aria-keyshortcuts="m+alt">메모 추가</button>
<button type="button" aria-keyshortcuts="D">삭제</button>

수정 키가 앞에 와야 하고(Alt+M), 수정 키 없는 한 글자 단축키는 화면낭독기의 빠른 탐색 키와 충돌합니다.

직접 해 보기

버튼을 누르거나, 페이지 어디서든 Alt+Shift+M(macOS는 Option+Shift+M)을 눌러 보세요. 같은 동작이 실행됩니다.

  • 첫 메모

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
aria-keyshortcuts가 있는 버튼에 포커스메모 추가, 버튼, Alt+Shift+M
단축키로 메모 추가메모 2을(를) 추가했습니다 (단축키).

사용 지침

이렇게 쓰세요

  • 실제로 구현한 단축키만 표시하고, 동작은 keydown으로 직접 처리합니다.
  • 수정 키를 먼저, 일반 키를 마지막에 두는 명세 형식을 지킵니다.
  • 화면에도 단축키를 표시해 모든 사용자가 알 수 있게 합니다.
  • 단축키를 끄거나 바꿀 수 있는 설정을 제공하면 더 좋습니다.

이렇게 쓰지 마세요

  • 수정 키 없는 한 글자 단축키를 전역으로 만들지 않습니다(WCAG 2.1.4).
  • 브라우저·운영체제·화면낭독기의 주요 단축키(Control+S, Insert 조합 등)를 덮어쓰지 않습니다.
  • accesskey와 다른 값을 함께 써서 혼란을 주지 않습니다.

사용할 수 있는 역할

전역 속성이므로 모든 역할과 HTML 요소에 쓸 수 있습니다. 특히 다음 역할과 자주 함께 씁니다.

buttonmenuitemlinktabtextboxsearchbox
aria-labelaria-describedby

이 속성을 쓰는 패턴

버튼과 토글 버튼

참고 자료