Документирование доступности

Для начала работы с библиотекой ally.js необходимо установить её через npm или подключить через CDN. Использование npm предоставляет возможность интеграции с современными сборщиками:

npm install ally.js

После установки библиотеку можно импортировать в проект:

import ally from 'ally.js';

Для быстрого прототипирования можно использовать подключение через CDN:

<script src="https://cdn.jsdelivr.net/npm/ally.js/dist/ally.min.js"></script>

Библиотека готова к использованию сразу после подключения.

Основные функции ally.js

Ally.js предназначена для анализа доступности интерфейсов и облегчения разработки ARIA-совместимых компонентов. Она предоставляет инструменты для:

  • Проверки фокуса и его состояния.
  • Управления навигацией по клавиатуре.
  • Определения видимости и интерактивности элементов.
  • Обнаружения скрытых и недоступных элементов.

Проверка фокуса

Метод ally.query.focus() возвращает объект с информацией о текущем элементе, имеющем фокус:

const focused = ally.query.focus();
console.log(focused.node); // HTML-элемент с фокусом
console.log(focused.tabindex); // значение tabindex

Можно использовать фильтры для поиска элементов с конкретными характеристиками:

const focusableElements = ally.query.focusable({
  context: document.body
});

focusableElements вернёт массив всех элементов, доступных для фокуса.

Работа с tabbable и focusable элементами

Focusable — элементы, которые могут получить фокус с помощью JavaScript (element.focus()). Tabbable — элементы, которые могут быть достигнуты с помощью клавиши Tab.

const tabbables = ally.query.tabbable({
  context: document.body
});

Использование этих методов позволяет управлять последовательностью навигации и создавать корректные сценарии клавиатурного взаимодействия.

Определение видимости и доступности

Метод ally.query.tabbable() автоматически исключает скрытые элементы, элементы с display: none, visibility: hidden и aria-hidden="true". Это обеспечивает точный анализ интерфейса.

Для проверки видимости отдельного элемента можно использовать ally.query.isVisible():

const element = document.querySelector('#button');
if (ally.query.isVisible(element)) {
  element.focus();
}

Обход ограничений фокуса

Ally.js позволяет определять элементы, которые технически доступны, но на практике недоступны для пользователя:

const limited = ally.query.focusable({
  context: document.body,
  filter: function(node) {
    return node.offsetParent !== null; // исключение скрытых элементов
  }
});

Использование фильтров повышает точность проверки и предотвращает ошибки в сценариях доступности.

Управление aria-атрибутами

Библиотека не только проверяет, но и помогает работать с ARIA:

const element = document.querySelector('#menu');
ally.maintain.tabFocus(element);

Метод maintain.tabFocus обеспечивает, чтобы фокус оставался внутри заданного контейнера. Это полезно для модальных окон, всплывающих меню и других интерактивных компонентов.

События и обратные вызовы

Ally.js предоставляет возможность реагировать на изменения фокуса:

const observer = ally.on.focus({
  context: document.body,
  callback: function(event) {
    console.log('Фокус переместился на:', event.target);
  }
});

Для отключения наблюдения используется observer.disengage():

observer.disengage();

Это позволяет динамически управлять обработкой фокуса в сложных интерфейсах.

Совместимость с DOM и Shadow DOM

Ally.js корректно работает с элементами внутри Shadow DOM. Для поиска tabbable элементов внутри Shadow DOM используется:

const shadowRoot = document.querySelector('#component').shadowRoot;
const tabbablesInShadow = ally.query.tabbable({ context: shadowRoot });

Такой подход позволяет интегрировать библиотеку в современные веб-компоненты без потери функциональности доступности.

Практическое использование

Типичные сценарии применения ally.js:

  1. Модальные окна: удержание фокуса внутри окна и предотвращение ухода за пределы.
  2. Динамические списки и меню: автоматическая проверка доступности добавленных элементов.
  3. Формы: определение доступных для ввода полей и управление последовательностью навигации.
  4. Тестирование интерфейсов: генерация отчётов о tabbable и focusable элементах для аудита доступности.
const modal = document.querySelector('#modal');
ally.maintain.tabFocus(modal);

const allFocusable = ally.query.focusable({ context: modal });
console.log(allFocusable.map(el => el.id));

Дополнительные возможности

  • ally.query.firstTabbable() — получение первого tabbable элемента в контейнере.
  • ally.query.lastTabbable() — получение последнего tabbable элемента.
  • ally.query.notFocusable() — поиск элементов, недоступных для фокуса, полезно для аудита и исправления ошибок.

Эти методы делают библиотеку гибким инструментом для построения интерфейсов, полностью совместимых со стандартами доступности.

Ally.js обеспечивает детальный контроль над фокусом, tabbable элементами и видимостью, что делает её незаменимой для разработки ARIA-дружественных интерфейсов в JavaScript.

Оглавление