ARIA-паттерны и клавиатурное взаимодействие
На собеседовании UI Engineer редко просят «рассказать про ARIA» в общем. Чаще дают практическую задачу: собрать tabs, диалог подтверждения, combobox с поиском или выпадающее меню — и проверить, работает ли это с клавиатуры и скринридера. Именно здесь видно разницу между разработчиком, который знает атрибуты, и тем, кто понимает модель взаимодействия.
Предыдущая статья — Доступность: WCAG 2.2, дерево доступности и аудит — объясняет, что видит вспомогательная технология и как проверять страницу. Эта статья про следующий слой: как устроены составные виджеты, какие роли и состояния им нужны, как управлять фокусом и что ломается в реальных приложениях — порталах, виртуализации и асинхронности.
Содержание
- Глубокий разбор
- Практические примеры
- Типичные ошибки и антипаттерны
- Ключевые тезисы для интервью
- Практическое задание и code review-чеклист
- Заключение
- Полезные ссылки
Глубокий разбор
Зачем нужен APG и когда хватит нативного элемента
ARIA Authoring Practices Guide (APG) — это не стандарт, а каталог проверенных паттернов: какие роли, состояния и клавиши ожидаются от tabs, dialog, menu, combobox, tree, grid и других виджетов. APG полезен как словарь ожиданий, но у него есть важная оговорка: это рекомендации, а не единственный допустимый способ.
Порядок принятия решений для UI Engineer выглядит так:
- Нативный элемент.
<button>,<a href>,<input>,<select>,<details>,<dialog>уже дают роль, фокус и клавиатурное поведение. Это лучший вариант. - Нативный элемент с небольшой доработкой. Например,
<dialog>плюс управление возвратом фокуса или<details>плюс синхронизацияaria-expanded, если это нужно дизайну. - APG-паттерн на составных элементах. Tabs, combobox, menu, tree, grid — там, где нативного аналога нет или он недостаточно гибок.
- Собственный паттерн. Только если он документирован, протестирован со скринридерами и не противоречит ожиданиям пользователей.
Главное правило: ARIA меняет семантику, но не добавляет поведение. <div role="tab" aria-selected="true"> не станет вкладкой: ему нужны tabindex, обработка стрелок, переключение панелей и визуальный фокус. Поэтому на интервью хороший ответ начинается не с атрибутов, а с вопроса: «а это точно не решается нативным элементом?»
Анатомия доступного виджета
У любого составного виджета есть пять слоёв, и пропуск любого из них виден пользователю:
| Слой | Вопрос | Примеры |
|---|---|---|
| Роль | Что это за элемент? | tablist, tab, dialog, listbox, menu |
| Имя | Как это называется? | видимый текст, aria-labelledby, aria-label |
| Состояние | Что с ним сейчас? | aria-expanded, aria-selected, aria-checked, aria-disabled |
| Связи | С чем это связано? | aria-controls, aria-describedby, aria-activedescendant |
| Поведение | Как этим управлять? | Tab, стрелки, Home/End, Enter, Space, Esc |
Роль без состояния бесполезна: кнопка с aria-expanded без обновления врёт скринридеру. Состояние без имени нечитаемо: пользователь слышит «свёрнуто», но не знает, что именно. Поведение без роли создаёт «див с обработчиком»: мышь работает, клавиатура — нет.
Есть и обратная крайность — ARIA-шум. Если навесить role="region" на каждую секцию, aria-live на весь список результатов и aria-label на каждый div, дерево доступности станет шумным, а навигация по landmarks потеряет смысл. Хорошая ARIA почти незаметна: она добавляет ровно те связи и состояния, которых не хватает нативной разметке.
Disclosure и accordion
Disclosure — самый простой паттерн: кнопка раскрывает и скрывает связанный блок. Он не требует role, потому что <button> уже даёт роль и клавиатуру.
<h3>
<button type="button" aria-expanded="false" aria-controls="shipping">
Доставка
</button>
</h3>
<div id="shipping" hidden>
<p>Курьером — 1–2 дня, самовывоз — в день заказа.</p>
</div>
const trigger = document.querySelector('[aria-controls="shipping"]');
const panel = document.getElementById('shipping');
trigger.addEventListener('click', () => {
const expanded = trigger.getAttribute('aria-expanded') === 'true';
trigger.setAttribute('aria-expanded', String(!expanded));
panel.hidden = expanded;
});
Что важно:
- Кнопка внутри заголовка. Заголовок сохраняет структуру страницы, а кнопка даёт фокус и активацию. Так пользователь может перейти к секции по заголовкам и раскрыть её.
aria-expandedобновляется синхронно с видимостью. Если анимация задерживает появление, состояние всё равно должно соответствовать тому, что скоро станет видно.aria-controlsполезен, но не критичен. Поддержка связи скринридерами нестабильна, поэтому не полагайтесь на неё как на единственный источник контекста.hiddenвместоaria-hidden. Скрытый блок не должен оставаться в tab-порядке.
Accordion — это несколько disclosure-блоков. В APG у него есть опциональная навигация стрелками между заголовками, Home/End и правила «один открыт» или «несколько открыты». Но принципиально это тот же механизм. Не превращайте accordion в tabs: в tabs выбран ровно один элемент и есть aria-selected, в accordion секции независимы.
Если панель большая и самостоятельная, ей можно дать role="region" и aria-labelledby на кнопку — тогда она появится в списке landmarks. Но злоупотреблять этим не стоит: десять region подряд превращают навигацию в лабиринт.
Tabs: roving tabindex и переключение панелей
Tabs — один из самых частых вопросов на практических интервью. Ожидаемая модель:
- контейнер —
role="tablist", у него есть доступное имя; - каждая вкладка —
role="tab",aria-selected,aria-controls; - панель —
role="tabpanel",aria-labelledbyна вкладку,tabindex="0"; - в tab-порядке вся группа занимает одну позицию: активная вкладка
tabindex="0", остальные-1; ←/→двигают фокус,Home/End— к краям;Enter/Spaceвыбирают вкладку при manual activation;Escне обязателен, если вкладки не находятся внутри другого overlay.
Есть два режима активации:
- Automatic activation — стрелка сразу переключает панель. Подходит, когда панели уже загружены и переключение дешёвое.
- Manual activation — стрелка только перемещает фокус, выбор происходит по
Enter/Space. Нужен, когда переключение запускает сетевой запрос или перерисовку, которую пользователь не хочет инициировать каждым нажатием.
В RTL-интерфейсе направление стрелок инвертируется: в dir="rtl" ArrowRight должен вести к предыдущей вкладке. Это частая деталь, которую забывают.
Dialog: фокус, inert и возврат
Диалог — место, где ломается больше всего сценариев. Контракт модального окна:
- Фокус внутри. При открытии он переходит в диалог, а не остаётся на фоне.
- Фон недоступен. Остальная страница не фокусируется и не кликается.
- Фокус не выходит наружу. Цикл
Tab/Shift+Tabзамыкается внутри. Escзакрывает. Если закрытие опасно (несохранённые данные), его можно перехватить и спросить подтверждение.- Фокус возвращается на триггер. Или на логически следующее место, если триггер исчез.
- Заголовок связан с диалогом.
aria-labelledbyнаh2внутри диалога.
Нативный <dialog> с showModal() закрывает пункты 2–4 сам: браузер делает остальной документ inert, удерживает фокус и закрывает по Esc. Это предпочтительный вариант для большинства случаев. Кастомная модалка (drawer, полноэкранный sheet, портал) требует ручной реализации всех пунктов.
Важная деталь: aria-hidden на фоне — неправильный инструмент. Он убирает фон из дерева доступности, но оставляет фокусируемые элементы в tab-порядке. Используйте inert — он убирает поддерево из дерева доступности, tab-порядка и событий. Подробнее — в статье про WCAG.
Куда ставить фокус при открытии:
- На первый осмысленный элемент — если диалог длинный и пользователь пришёл что-то читать или заполнять.
- На сам диалог (
tabindex="-1") — если контент статичный и первый элемент случайный. - На безопасное действие — «Отмена», а не «Удалить». Иначе случайный
Enterвыполнит деструктивную операцию.
Не ставьте автофокус на поле, если диалог открылся после действия пользователя и он ещё не решил, что вводить: это может вызвать нежелательную мобильную клавиатуру и сбить контекст.
Menu и menubar: почему не для навигации
role="menu" — самый неправильно используемый паттерн. Он нужен для меню команд, как в десктопных приложениях: «Переименовать», «Дублировать», «Удалить». У него особый режим взаимодействия:
Tabне ходит по пунктам: он входит в меню и выходит из него;- стрелки
↑/↓перемещают фокус междуmenuitem; Home/End— к первому и последнему пункту;Enter/Spaceактивируют пункт;Escзакрывает меню и возвращает фокус на кнопку;- набор символов (typeahead) перемещает к пункту, начинающемуся с этих букв.
Для навигации по сайту это не подходит. Ссылки в шапке — это <nav> со списком <a>, где работают обычный Tab и режим чтения скринридера. Если навесить menu на список ссылок, пользователь VoiceOver/NVDA попадёт в режим, где ожидаются команды и стрелки, а получит переходы по страницам.
Правильные альтернативы:
| Задача | Паттерн |
|---|---|
| Раскрыть блок с ссылками или текстом | Disclosure |
| Кнопка с меню действий | Menu button + role="menu" |
| Верхнее меню приложения с командами | Menubar + role="menubar" |
| Навигация по сайту | <nav> + ссылки/список |
Menu button — это кнопка с aria-haspopup="menu", aria-expanded и aria-controls, которая открывает меню и переводит фокус на первый пункт. При закрытии фокус возвращается на кнопку. Вложенные меню (submenu) добавляют aria-haspopup="menu", aria-expanded и открытие по →, но сложность быстро растёт: если вложенность не обязательна, лучше упростить интерфейс.
Listbox и combobox: activedescendant против roving tabindex
Combobox — поле ввода с выпадающим списком. В ARIA 1.2 модель такая:
<label for="city">Город</label>
<input
id="city"
role="combobox"
aria-expanded="false"
aria-controls="city-listbox"
aria-autocomplete="list"
autocomplete="off"
>
<ul id="city-listbox" role="listbox" aria-label="Города" hidden>
<li role="option" id="city-option-0" aria-selected="false">Москва</li>
<li role="option" id="city-option-1" aria-selected="false">Санкт-Петербург</li>
</ul>
Ключевое отличие от нативного <select>: фокус остаётся в поле ввода. Пользователь продолжает печатать, а скринридер объявляет активный вариант через aria-activedescendant:
<input aria-activedescendant="city-option-1" ...>
Два подхода к навигации:
aria-activedescendant | Roving tabindex | |
|---|---|---|
| Где DOM-фокус | На контейнере или поле | На активном элементе |
| Кто получает фокус | Один элемент | Каждый элемент по очереди |
| Типичные паттерны | Combobox, listbox, grid | Tabs, menu, toolbar |
| Плюсы | Ввод не прерывается, меньше DOM-фокусов | Естественная работа скринридера с элементом |
| Минусы | Нужны стабильные id и элемент в DOM | Нужно управлять tabindex при каждом переходе |
Для combobox aria-activedescendant почти всегда лучше: иначе при перемещении фокуса в список пользователь перестаёт печатать. Для tabs и menu — roving tabindex: там сам фокус и есть выбор.
Состояния combobox:
aria-expanded="true|false"— открыт ли список;aria-controls— id listbox;aria-autocomplete="list"— список подсказывает варианты;aria-selected="true"на активном варианте (в single-select listbox);aria-activedescendant— id активного варианта;aria-busy="true"на listbox или статус-регионе — пока идёт загрузка.
Клавиатура:
↓— открыть список и перейти к первому варианту;↑/↓— двигать активный вариант;Alt+↓— открыть список, не меняя ввод;Enter— выбрать активный вариант;Esc— закрыть список, не очищая ввод;Tab— закрыть список и уйти к следующему полю;Home/End— к первому/последнему варианту, если курсор не в тексте.
Tooltip, grid и tree: коротко о границах
Tooltip — это подсказка, а не интерактивный элемент. Она появляется по hover и focus, связана с триггером через aria-describedby, закрывается по Esc и не содержит кнопок или ссылок. Если внутри есть действия, это уже popover или dialog, а не tooltip. На touch tooltip по hover недоступен, поэтому важная информация не должна жить только в нём.
Grid (role="grid") — интерактивная таблица с ячейками, по которым ходят стрелками. Это не «таблица для раскладки» и не замена <table> для статичных данных. Если данные только читают, используйте <table> с <caption>, <th scope> и нативными заголовками. role="grid" оправдан для редактируемых таблиц, календарей и spreadsheet-подобных интерфейсов, где нужна двумерная навигация.
Tree (role="tree", treeitem, group) — иерархия с раскрытием узлов: файловое дерево, категории, оглавление. Клавиши: ↑/↓ между видимыми узлами, → раскрыть или перейти к первому ребёнку, ← свернуть или подняться к родителю, Home/End — к краям. Если иерархия неглубокая и не требует клавиатурной навигации, хватит вложенных списков и disclosure.
Live regions: как объявлять изменения
Live region — механизм, который сообщает скринридеру об изменении контента без перемещения фокуса. Это нужно для статусов, ошибок, результатов поиска и уведомлений.
| Атрибут/роль | Поведение | Когда использовать |
|---|---|---|
role="status" | Неявно aria-live="polite", aria-atomic="true" | Загрузка, сохранение, «5 результатов» |
role="alert" | Неявно aria-live="assertive", aria-atomic="true" | Критичная ошибка, требующая немедленной реакции |
role="log" | Вежливые добавления, старые сообщения сохраняются | Чат, журнал событий |
aria-live="polite" | Объявляет после текущей речи | Большинство динамики |
aria-live="assertive" | Прерывает текущую речь | Только критичное |
aria-atomic="true" | Читает регион целиком | Когда важен полный текст сообщения |
Правила, которые чаще всего нарушают:
- Регион должен существовать до изменения. Если создать
<div role="status">и текст одновременно, скринридер может не успеть подписаться. Контейнер рендерят заранее, а меняют только его содержимое. - Не объявляйте каждое нажатие. Фильтрация по каждой букве с
aria-liveпревращается в поток. Дебаунсьте и объявляйте итог: «Найдено 5 городов». assertive— не «важнее», а «громче». Он перебивает пользователя. Для ошибок валидации после submit обычно достаточно фокуса на error summary, а для асинхронной проверки —polite.- Один регион — одна мысль. Длинный текст в
role="alert"читается целиком и блокирует остальное. - Не дублируйте объявление.
role="alert"плюс перевод фокуса на тот же блок часто дают двойное чтение.
<!-- Регион существует заранее, текст меняется позже -->
<p id="search-status" role="status" aria-atomic="true"></p>
const status = document.querySelector('#search-status');
function announce(message) {
status.textContent = '';
// Небольшая пауза помогает некоторым скринридерам заметить изменение
requestAnimationFrame(() => {
status.textContent = message;
});
}
Сложные случаи: порталы, виртуализация, мобильные скринридеры
Порталы и Teleport. Диалог, поповер или меню часто рендерят в конец <body>, чтобы не бороться с overflow: hidden и stacking context. Проблемы:
- DOM-порядок перестаёт совпадать с визуальным —
Tabможет уйти не туда; aria-labelledbyссылается на заголовок, который остался в другом поддереве;- возврат фокуса ломается, если триггер размонтирован;
- фон нужно изолировать через
inert, а неaria-hidden.
Решение: хранить ссылку на триггер, после закрытия возвращать фокус, держать заголовок и описание внутри портала, а фон изолировать inert. Если диалогов два, вложенность должна быть осмысленной: второй диалог поверх первого — это отдельный слой с собственным inert на нижележащем.
Виртуализированные списки. В списке из 10 000 элементов в DOM живут только 20. Скринридер видит неполный список, а aria-activedescendant может указывать на вариант, которого уже нет. Что помогает:
aria-setsizeиaria-posinsetна каждом варианте — сообщают общий размер и позицию;- стабильные id, не зависящие от индекса в окне;
- активный вариант всегда остаётся в DOM;
- для небольших списков (до нескольких сотен) виртуализацию лучше не включать;
- при прокрутке не перемещать фокус без действия пользователя.
Мобильные скринридеры. VoiceOver и TalkBack работают иначе: есть режим обхода касанием, ротор и виртуальный курсор. Слишком агрессивное управление фокусом, aria-live на каждом шаге и кастомные жесты часто раздражают сильнее, чем помогают. Проверяйте не только десктопный NVDA, но и мобильный сценарий, особенно для combobox, date picker и drag-and-drop.
Вложенные интерактивные элементы. Кнопка внутри ссылки, ссылка внутри кнопки, кнопка внутри label — невалидная и непредсказуемая комбинация. Скринридер видит один элемент, а клавиатура — другой. Разделяйте действия на соседние элементы.
Практические примеры
Пример 1. Доступные tabs на чистом JS и в React
<div class="tabs">
<div role="tablist" aria-label="Настройки профиля">
<button
role="tab"
id="tab-profile"
aria-controls="panel-profile"
aria-selected="true"
tabindex="0"
>Профиль</button>
<button
role="tab"
id="tab-security"
aria-controls="panel-security"
aria-selected="false"
tabindex="-1"
>Безопасность</button>
<button
role="tab"
id="tab-notifications"
aria-controls="panel-notifications"
aria-selected="false"
tabindex="-1"
>Уведомления</button>
</div>
<div role="tabpanel" id="panel-profile" aria-labelledby="tab-profile" tabindex="0">
...
</div>
<div role="tabpanel" id="panel-security" aria-labelledby="tab-security" tabindex="0" hidden>
...
</div>
<div role="tabpanel" id="panel-notifications" aria-labelledby="tab-notifications" tabindex="0" hidden>
...
</div>
</div>
const tablist = document.querySelector('[role="tablist"]');
const tabs = [...tablist.querySelectorAll('[role="tab"]')];
function selectTab(next, { focus = true } = {}) {
if (next.getAttribute('aria-selected') === 'true') return;
for (const tab of tabs) {
const selected = tab === next;
tab.setAttribute('aria-selected', String(selected));
tab.tabIndex = selected ? 0 : -1;
document.getElementById(tab.getAttribute('aria-controls')).hidden = !selected;
}
if (focus) next.focus();
}
tablist.addEventListener('click', (event) => {
const tab = event.target.closest('[role="tab"]');
if (tab) selectTab(tab);
});
tablist.addEventListener('keydown', (event) => {
const index = tabs.indexOf(document.activeElement);
if (index === -1) return;
let next;
switch (event.key) {
case 'ArrowRight':
next = tabs[(index + 1) % tabs.length];
break;
case 'ArrowLeft':
next = tabs[(index - 1 + tabs.length) % tabs.length];
break;
case 'Home':
next = tabs[0];
break;
case 'End':
next = tabs[tabs.length - 1];
break;
default:
return;
}
event.preventDefault();
selectTab(next);
});
Почему так:
- вся группа — одна остановка
Tab, дальше работают стрелки; aria-selectedиhiddenменяются вместе, состояние не врёт;Home/Endдают быстрый доступ к краям;- панель с
tabindex="0"позволяет с клавиатуры войти в её содержимое и прочитать его.
Для manual activation уберите вызов selectTab из keydown и оставьте только перемещение фокуса:
next.focus();
// выбор — по Enter/Space
tablist.addEventListener('keydown', (event) => {
if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
selectTab(document.activeElement);
}
});
В React та же логика живёт в состоянии, а не в DOM:
import { useId, useRef, useState } from 'react';
type Tab = { id: string; label: string; content: React.ReactNode };
export function Tabs({ items, label }: { items: Tab[]; label: string }) {
const baseId = useId();
const [active, setActive] = useState(0);
const refs = useRef<(HTMLButtonElement | null)[]>([]);
function onKeyDown(event: React.KeyboardEvent) {
let next = active;
if (event.key === 'ArrowRight') next = (active + 1) % items.length;
else if (event.key === 'ArrowLeft') next = (active - 1 + items.length) % items.length;
else if (event.key === 'Home') next = 0;
else if (event.key === 'End') next = items.length - 1;
else return;
event.preventDefault();
setActive(next);
refs.current[next]?.focus();
}
return (
<div>
<div role="tablist" aria-label={label} onKeyDown={onKeyDown}>
{items.map((item, index) => {
const selected = index === active;
return (
<button
key={item.id}
ref={(node) => { refs.current[index] = node; }}
role="tab"
id={`${baseId}-tab-${item.id}`}
aria-controls={`${baseId}-panel-${item.id}`}
aria-selected={selected}
tabIndex={selected ? 0 : -1}
onClick={() => setActive(index)}
>
{item.label}
</button>
);
})}
</div>
{items.map((item, index) => (
<div
key={item.id}
role="tabpanel"
id={`${baseId}-panel-${item.id}`}
aria-labelledby={`${baseId}-tab-${item.id}`}
tabIndex={0}
hidden={index !== active}
>
{item.content}
</div>
))}
</div>
);
}
useId здесь не украшение: без уникальных id несколько экземпляров tabs на странице начнут ссылаться на чужие панели.
Пример 2. Нативный dialog с возвратом фокуса
<button type="button" id="open-settings" aria-haspopup="dialog">
Настройки
</button>
<dialog id="settings-dialog" aria-labelledby="settings-title">
<h2 id="settings-title">Настройки уведомлений</h2>
<label>
<input type="checkbox" checked>
Присылать дайджест раз в неделю
</label>
<div class="dialog-actions">
<button type="button" data-close>Отмена</button>
<button type="submit">Сохранить</button>
</div>
</dialog>
const dialog = document.querySelector('#settings-dialog');
const trigger = document.querySelector('#open-settings');
trigger.addEventListener('click', () => {
dialog.showModal();
dialog.querySelector('[data-close]').focus();
});
dialog.querySelector('[data-close]').addEventListener('click', () => {
dialog.close();
});
dialog.addEventListener('click', (event) => {
// Клик по backdrop приходит с target === dialog
if (event.target === dialog) dialog.close();
});
dialog.addEventListener('close', () => {
trigger.focus();
});
Что делает браузер:
showModal()добавляет диалог в top layer и делает остальной документinert;- фокус удерживается внутри,
Escвызываетcancelи закрывает диалог; ::backdropпозволяет стилизовать затемнение без отдельного оверлея;- после закрытия современные браузеры возвращают фокус на триггер, но явный вызов делает поведение предсказуемым и в кастомных сценариях.
Чего не хватает нативному <dialog>:
- Стилизация ограничена, но
::backdropи обычный CSS закрывают большинство задач. - Анимация требует
@starting-styleиtransition-behavior: allow-discrete— это тема отдельной статьи про motion. - Вложенные диалоги работают, но требуют аккуратного возврата фокуса: закрывайте верхний и возвращайте фокус на элемент, который его открыл, а не сразу на исходный триггер.
Если дизайн требует кастомный drawer или sheet, минимум такой:
function openDrawer(drawer, trigger) {
const app = document.querySelector('#app');
const previous = document.activeElement;
app.inert = true;
drawer.hidden = false;
const initial = drawer.querySelector('[data-autofocus]') ?? drawer;
initial.focus();
return () => {
drawer.hidden = true;
app.inert = false;
(trigger ?? previous)?.focus();
};
}
Это только каркас: ещё нужны цикл Tab, закрытие по Esc, блокировка прокрутки и корректная работа с порталом. У самого drawer должен быть tabindex="-1", иначе drawer.focus() не сработает.
Пример 3. Combobox с aria-activedescendant и асинхронным поиском
<div class="combobox">
<label for="city">Город</label>
<input
id="city"
role="combobox"
aria-expanded="false"
aria-controls="city-listbox"
aria-autocomplete="list"
autocomplete="off"
placeholder="Начните вводить"
>
<ul id="city-listbox" role="listbox" aria-label="Города" hidden></ul>
<p id="city-status" role="status" aria-atomic="true"></p>
</div>
const input = document.querySelector('#city');
const listbox = document.querySelector('#city-listbox');
const status = document.querySelector('#city-status');
let options = [];
let activeIndex = -1;
let controller;
function setExpanded(expanded) {
input.setAttribute('aria-expanded', String(expanded));
listbox.hidden = !expanded;
}
function render(items, query) {
options = items;
activeIndex = items.length > 0 ? 0 : -1;
listbox.replaceChildren(
...items.map((item, index) => {
const option = document.createElement('li');
option.id = `city-option-${item.id}`;
option.setAttribute('role', 'option');
option.setAttribute('aria-selected', String(index === activeIndex));
option.textContent = item.label;
option.addEventListener('mousedown', (event) => {
event.preventDefault();
choose(item);
});
return option;
}),
);
setExpanded(items.length > 0);
setActive(activeIndex);
if (items.length === 0) {
status.textContent = query
? `Ничего не найдено по запросу «${query}»`
: '';
} else {
status.textContent = `Найдено ${items.length}`;
}
}
function setActive(index) {
activeIndex = index;
const active = options[index];
if (!active) {
input.removeAttribute('aria-activedescendant');
return;
}
input.setAttribute('aria-activedescendant', `city-option-${active.id}`);
for (const option of listbox.children) {
option.setAttribute(
'aria-selected',
String(option.id === `city-option-${active.id}`),
);
}
listbox.querySelector(`#city-option-${active.id}`)?.scrollIntoView({ block: 'nearest' });
}
function choose(item) {
input.value = item.label;
setExpanded(false);
input.removeAttribute('aria-activedescendant');
status.textContent = `Выбран город ${item.label}`;
}
input.addEventListener('input', async () => {
const query = input.value.trim();
controller?.abort();
controller = new AbortController();
if (query.length < 2) {
render([], '');
return;
}
status.textContent = 'Загрузка…';
try {
const response = await fetch(`/api/cities?q=${encodeURIComponent(query)}`, {
signal: controller.signal,
});
if (!response.ok) throw new Error('request failed');
render(await response.json(), query);
} catch (error) {
if (error.name !== 'AbortError') {
render([], query);
status.textContent = 'Не удалось загрузить города. Попробуйте ещё раз.';
}
}
});
input.addEventListener('keydown', (event) => {
switch (event.key) {
case 'ArrowDown':
event.preventDefault();
if (listbox.hidden) setExpanded(true);
setActive(Math.min(activeIndex + 1, options.length - 1));
break;
case 'ArrowUp':
event.preventDefault();
setActive(Math.max(activeIndex - 1, 0));
break;
case 'Home':
if (input.selectionStart === 0) {
event.preventDefault();
setActive(0);
}
break;
case 'End':
if (input.selectionStart === input.value.length) {
event.preventDefault();
setActive(options.length - 1);
}
break;
case 'Enter':
if (activeIndex >= 0 && !listbox.hidden) {
event.preventDefault();
choose(options[activeIndex]);
}
break;
case 'Escape':
if (!listbox.hidden) {
event.preventDefault();
setExpanded(false);
}
break;
case 'Tab':
setExpanded(false);
break;
}
});
Что здесь важно:
- фокус не покидает поле — пользователь продолжает печатать;
activeIndexиaria-selectedсинхронизированы;AbortControllerотменяет устаревший запрос, чтобы результаты не перезаписывали друг друга;- загрузка, пустой результат и ошибка объявляются в
role="status"безassertive; mousedownсpreventDefaultне даёт полю потерять фокус при клике по варианту;- выбор мышью и с клавиатуры проходит через одну функцию.
Чего в примере нет и что нужно в продакшене: debounce ввода, кэширования, клавиши Alt+ArrowDown, подсветки совпадения, обработки IME-композиции и мобильного поведения. Но базовая модель уже корректна.
Во Vue тот же виджет удобно собирать на ref + watch:
<script setup lang="ts">
import { ref, watch } from 'vue';
const query = ref('');
const options = ref<{ id: string; label: string }[]>([]);
const activeIndex = ref(-1);
const expanded = ref(false);
let controller: AbortController | undefined;
watch(query, async (value) => {
controller?.abort();
controller = new AbortController();
if (value.trim().length < 2) {
options.value = [];
expanded.value = false;
return;
}
const response = await fetch(`/api/cities?q=${encodeURIComponent(value)}`, {
signal: controller.signal,
}).catch((error) => {
if (error.name !== 'AbortError') throw error;
});
if (response?.ok) {
options.value = await response.json();
expanded.value = options.value.length > 0;
activeIndex.value = expanded.value ? 0 : -1;
}
});
</script>
Шаблон и клавиатурная логика остаются такими же: роль combobox на поле, listbox на списке, aria-activedescendant на активном варианте.
Пример 4. Menu button с roving tabindex
<button
type="button"
id="actions-button"
aria-haspopup="menu"
aria-expanded="false"
aria-controls="actions-menu"
>
Действия
</button>
<ul id="actions-menu" role="menu" aria-labelledby="actions-button" hidden>
<li role="none"><button type="button" role="menuitem" tabindex="-1">Переименовать</button></li>
<li role="none"><button type="button" role="menuitem" tabindex="-1">Дублировать</button></li>
<li role="none"><button type="button" role="menuitem" tabindex="-1">Удалить</button></li>
</ul>
const button = document.querySelector('#actions-button');
const menu = document.querySelector('#actions-menu');
const items = [...menu.querySelectorAll('[role="menuitem"]')];
function openMenu() {
menu.hidden = false;
button.setAttribute('aria-expanded', 'true');
items[0].tabIndex = 0;
items[0].focus();
}
function closeMenu({ focusButton = true } = {}) {
menu.hidden = true;
button.setAttribute('aria-expanded', 'false');
items.forEach((item) => { item.tabIndex = -1; });
if (focusButton) button.focus();
}
function focusItem(index) {
items.forEach((item, i) => { item.tabIndex = i === index ? 0 : -1; });
items[index].focus();
}
button.addEventListener('click', () => {
menu.hidden ? openMenu() : closeMenu();
});
button.addEventListener('keydown', (event) => {
if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
openMenu();
}
});
menu.addEventListener('keydown', (event) => {
const index = items.indexOf(document.activeElement);
if (event.key === 'Escape') {
event.preventDefault();
closeMenu();
} else if (event.key === 'ArrowDown') {
event.preventDefault();
focusItem((index + 1) % items.length);
} else if (event.key === 'ArrowUp') {
event.preventDefault();
focusItem((index - 1 + items.length) % items.length);
} else if (event.key === 'Home') {
event.preventDefault();
focusItem(0);
} else if (event.key === 'End') {
event.preventDefault();
focusItem(items.length - 1);
} else if (event.key === 'Tab') {
// Закрываем меню и возвращаем фокус на кнопку,
// чтобы следующая остановка Tab была предсказуемой.
event.preventDefault();
closeMenu();
}
});
document.addEventListener('pointerdown', (event) => {
if (!menu.hidden && !menu.contains(event.target) && !button.contains(event.target)) {
closeMenu({ focusButton: false });
}
});
Дополнительно нужен typeahead: нажатие буквы перемещает к первому пункту, начинающемуся с неё. В меню действий это заметно улучшает работу с клавиатуры, особенно если пунктов больше пяти.
Пример 5. Error summary и вежливое объявление результата
<form id="profile-form" novalidate>
<div id="form-errors" role="group" aria-labelledby="form-errors-title" tabindex="-1" hidden>
<h2 id="form-errors-title">Проверьте поля</h2>
<ul></ul>
</div>
<label for="email">Email</label>
<input id="email" name="email" type="email" autocomplete="email" aria-describedby="email-error">
<p id="email-error" hidden>Введите email в формате name@example.com</p>
<button type="submit">Сохранить</button>
</form>
const form = document.querySelector('#profile-form');
const summary = document.querySelector('#form-errors');
const summaryList = summary.querySelector('ul');
form.addEventListener('submit', (event) => {
event.preventDefault();
const invalid = [...form.elements].filter(
(field) => field.willValidate && !field.checkValidity(),
);
for (const field of form.querySelectorAll('[aria-invalid="true"]')) {
field.removeAttribute('aria-invalid');
document.getElementById(`${field.id}-error`).hidden = true;
}
summary.hidden = true;
summaryList.replaceChildren();
if (invalid.length === 0) {
form.submit();
return;
}
for (const field of invalid) {
field.setAttribute('aria-invalid', 'true');
document.getElementById(`${field.id}-error`).hidden = false;
const item = document.createElement('li');
const link = document.createElement('a');
link.href = `#${field.id}`;
link.textContent = field.labels?.[0]?.textContent ?? field.name;
item.append(link);
summaryList.append(item);
}
summary.hidden = false;
summary.focus();
});
Почему не role="alert" на summary:
- фокус уже переводится на блок — скринридер прочитает заголовок и список;
alertвместе с фокусом может дать двойное объявление;- ошибки не исчезают, пользователь может вернуться к ним в любой момент.
Асинхронную проверку (например, «email уже занят») лучше объявлять отдельно и вежливо:
<p id="email-async" role="status" aria-atomic="true"></p>
async function checkEmail(email) {
const status = document.querySelector('#email-async');
status.textContent = 'Проверяем email…';
const response = await fetch(`/api/email-available?email=${encodeURIComponent(email)}`);
const { available } = await response.json();
status.textContent = available ? 'Email свободен' : 'Этот email уже занят';
}
Типичные ошибки и антипаттерны
role="menu"на навигации сайта. Скринридер переключается в режим команд, а пользователь ожидает ссылки. Для навигации —<nav>и<a href>.tabindex="0"на каждой вкладке. Группа перестаёт быть одной остановкойTab, roving tabindex ломается. Активная —0, остальные —-1.aria-selectedбезtabindexи стрелок. Состояние есть, поведения нет; с клавиатуры вкладки недоступны.hiddenиaria-hiddenвперемешку. Скрытая панель сaria-hiddenостаётся фокусируемой; используйтеhiddenилиinert.- Модалка без возврата фокуса. После закрытия фокус уходит в
body, и пользователь начинаетTabс начала страницы. - Фокус на деструктивной кнопке при открытии. Случайный
Enterудаляет данные; ставьте фокус на «Отмена» или на диалог. aria-hiddenна фоне вместоinert. Фон исчезает из дерева доступности, но остаётся в tab-порядке.role="alert"на каждом изменении. Каждое нажатие перебивает речь; используйтеrole="status".- Live-регион создаётся вместе с текстом. Скринридер может не успеть подписаться; контейнер должен быть в DOM заранее.
aria-expandedне обновляется. Скринридер сообщает ложное состояние — это хуже, чем отсутствие атрибута.aria-activedescendantуказывает на несуществующий id. Частое следствие виртуализации или фильтрации; активный вариант должен быть в DOM.- Фокус уходит в список при вводе. В combobox фокус остаётся в поле, иначе пользователь не может печатать.
- Tooltip с кнопками внутри. Tooltip не интерактивен; для действий нужен popover или dialog.
aria-labelперекрывает видимый текст. Ломает Label in Name и голосовое управление; видимая подпись должна входить в имя.role="application"на всём приложении. Отключает привычные режимы скринридера и почти всегда ухудшает навигацию.- Автофокус на поле в мобильном диалоге. Вызывает клавиатуру и сбивает контекст; фокус лучше ставить на диалог или безопасное действие.
- Проверка только мышью. Клавиатурный сценарий и скринридер не проверены — значит, паттерн не готов.
Ключевые тезисы для интервью
- Сначала нативный элемент, потом APG, потом своя реализация.
<dialog>,<details>,<button>и<select>закрывают больше сценариев, чем кажется. - ARIA меняет семантику, но не поведение. Роль
tabбез roving tabindex, стрелок иaria-selected— этоdiv, который выглядит как вкладка. - У виджета пять слоёв: роль, имя, состояние, связи, поведение. Пропуск любого виден пользователю скринридера или клавиатуры.
- Tabs — одна остановка
Tab. Активная вкладкаtabindex="0", остальные-1, стрелки иHome/End, панель связана черезaria-labelledby. - Dialog удерживает фокус и возвращает его. Нативный
showModal()делает фонinert; кастомной модалке нужныinert, цикл фокуса и восстановление. aria-activedescendantи roving tabindex решают разные задачи. Первый — для combobox/listbox с вводом, второй — для tabs/menu/toolbar.role="menu"— это меню команд, а не навигация. Для ссылок в шапке нужен<nav>, для раскрывающегося блока — disclosure.- Combobox держит фокус в поле. Активный вариант помечается
aria-activedescendant, загрузка и пустой результат объявляются вежливо. - Live regions должны существовать заранее.
polite— для большинства обновлений,assertive— только для критичного; не дублируйте объявление фокусом. - Порталы и виртуализация ломают связи. Возвращайте фокус, держите заголовок рядом с диалогом, используйте
aria-setsize/aria-posinsetи не размонтируйте активный вариант. - Клавиатура — часть Definition of Done.
Tab, стрелки,Home/End,Enter,Space,Escи возврат фокуса проверяются в e2e и руками.
Практическое задание и code review-чеклист
Задание: собрать три паттерна и проверить клавиатурой
Соберите на одной странице:
- Tabs с тремя вкладками, roving tabindex,
Home/Endи переключением панелей. - Dialog подтверждения удаления: нативный
<dialog>, фокус на «Отмена»,Esc, возврат фокуса на триггер. - Combobox с асинхронным поиском: загрузка, пустой результат, выбор мышью и с клавиатуры,
aria-activedescendant.
Проверьте:
- пройдите страницу только клавиатурой:
Tab,Shift+Tab, стрелки,Home/End,Enter,Space,Esc; - убедитесь, что фокус видим и нигде не проваливается;
- включите NVDA + Firefox или VoiceOver + Safari и проверьте объявления ролей, состояний и результатов;
- отключите мышь и попробуйте выполнить тот же сценарий;
- проверьте RTL: стрелки в tabs должны инвертироваться;
- прогоните axe и добавьте клавиатурный e2e-тест в Playwright.
Чек-лист code review доступного компонента
- Использован нативный элемент, если он закрывает сценарий; ARIA не дублирует семантику.
- У каждой роли есть доступное имя, а у виджета — понятная инструкция или очевидная модель.
- Состояния (
aria-expanded,aria-selected,aria-checked,aria-disabled) обновляются вместе с UI. - Вся группа — одна остановка
Tab; внутри работают стрелки,Home/End,Enter/Space. -
Escзакрывает overlay и возвращает фокус; ловушек клавиатуры нет. - Модальный диалог переводит фокус внутрь и возвращает на триггер; фон изолирован через
inert. - Активная вкладка имеет
tabindex="0", остальные-1; панель связана черезaria-labelledby. - Combobox держит фокус в поле;
aria-activedescendantуказывает на существующий вариант. - Live-регион существует в DOM заранее;
assertiveиспользован только для критичных ошибок. - Ошибки формы связаны с полями через
aria-invalidиaria-describedby, фокус переходит к проблеме. - Portal/Teleport не ломает порядок фокуса,
aria-labelledbyи возврат фокуса. - Виртуализированный список сообщает
aria-setsize/aria-posinsetи не размонтирует активный вариант. -
aria-labelне перекрывает видимый текст; иконочные кнопки имеют имя. - Есть клавиатурный e2e-тест и ручная проверка скринридером.
- Компонент проверен в RTL и на мобильном скринридере, если это часть продукта.
Заключение
Доступный виджет — это не набор ARIA-атрибутов, а договор о поведении. Пользователь клавиатуры ожидает, что Tab войдёт в компонент один раз, стрелки подвинут фокус, Esc закроет overlay, а фокус вернётся туда, откуда пришёл. Пользователь скринридера ожидает, что роль, имя и состояние совпадают с тем, что происходит на экране.
APG даёт готовые модели для tabs, dialog, menu, combobox, tree и grid, но применять их нужно осознанно: сначала нативный элемент, потом паттерн, потом собственная реализация. Самое сложное начинается не в разметке, а в интеграции — порталы, виртуализация, асинхронность и мобильные скринридеры. Именно там проверяется, понимает ли UI Engineer модель фокуса и дерева доступности, а не только набор атрибутов.
Следующий шаг — автоматизация: как встроить axe, клавиатурные сценарии и скринридер-проверки в CI. Об этом — Тестирование доступности. Vue-специфика компонентов разобрана в Доступные компоненты во Vue, а API компонентов и выбор библиотеки — в UI-киты, headless-компоненты и Storybook.