Полный список методов ally.get

Библиотека ally.js предназначена для упрощения работы с доступностью (accessibility) в веб-приложениях. Метод ally.get предоставляет набор функций для получения информации о состоянии элементов на странице, их доступности и видимости для пользователей с особыми потребностями. Ниже представлен подробный разбор основных методов и их применения.

ally.get.activeElement([context])

Возвращает элемент, который в данный момент имеет фокус в пределах указанного context. Если контекст не указан, поиск осуществляется по всему документу.

Параметры:

  • context (optional) — DOM-элемент или Document, в пределах которого ищется активный элемент.

Особенности:

  • Учитывает Shadow DOM и iframe.
  • Возвращает null, если фокус отсутствует.
  • Может быть использован для реализации кастомных компонентов с управлением клавиатурным фокусом.

Пример использования:

const active = ally.get.activeElement();
console.log(active); // <input id="search" />

ally.get.tabbed()

Возвращает массив элементов, которые могут быть достигнуты с помощью клавиши Tab. Метод анализирует все интерактивные элементы страницы и фильтрует их по доступности.

Возвращает:

  • Массив объектов с ключами:

    • node — сам DOM-элемент
    • tabindex — значение атрибута tabindex
    • disabled — булевое значение, указывающее на отключённость элемента

Особенности:

  • Игнорирует скрытые элементы (display: none или visibility: hidden).
  • Учитывает ARIA-атрибуты и состояния aria-hidden.

Пример использования:

const tabElements = ally.get.tabbed();
tabElements.forEach(el => console.log(el.node.tagName));

ally.get.focusable([context])

Возвращает все элементы, на которые можно установить фокус. Метод шире, чем tabbed(), так как включает элементы с tabindex="-1" и другие интерактивные элементы, доступные программно.

Параметры:

  • context (optional) — DOM-узел для ограничения поиска.

Особенности:

  • Полезно для построения модальных окон и кастомных диалогов.
  • Учитывает элементы с ARIA-ролями, которые могут принимать фокус.

Пример использования:

const focusableElements = ally.get.focusable(document.getElementById('modal'));
focusableElements.forEach(el => el.node.focus());

ally.get.ignored([context])

Возвращает элементы, которые игнорируются assistive-технологиями, например, экранными читалками.

Особенности:

  • Фильтрует элементы с aria-hidden="true".
  • Учитывает вложенные элементы, скрытые родительскими контейнерами.
  • Полезно для проверки корректности ARIA-разметки.

Пример использования:

const hiddenElements = ally.get.ignored();
hiddenElements.forEach(el => console.log(el.node.id));

ally.get.textNodes([context])

Возвращает массив всех текстовых узлов внутри указанного контекста, которые видимы и доступны пользователю.

Особенности:

  • Исключает пустые текстовые узлы.
  • Игнорирует элементы с CSS-стилями display: none и visibility: hidden.
  • Может быть использован для анализа контента на доступность.

Пример использования:

const texts = ally.get.textNodes(document.body);
texts.forEach(node => console.log(node.textContent.trim()));

ally.get.parents(node)

Возвращает массив родителей указанного узла до корня документа. Полезно для определения контекста элемента и его взаимодействия с ARIA-атрибутами.

Возвращает:

  • Массив объектов с ключами:

    • node — родительский DOM-элемент
    • role — ARIA-роль родителя (если указана)
    • ignored — булево значение, если родитель скрыт от assistive-технологий

Пример использования:

const parents = ally.get.parents(document.getElementById('button1'));
parents.forEach(parent => console.log(parent.node.tagName, parent.role));

ally.get.query()

Общий метод, который позволяет получить информацию о любом наборе элементов с кастомными фильтрами.

Параметры:

  • context — DOM-узел для поиска.
  • filter — функция для фильтрации элементов. Должна возвращать true для включения элемента в результат.

Особенности:

  • Позволяет объединять функции tabbed, focusable, ignored в один запрос.
  • Может использоваться для построения динамических отчётов о доступности страницы.

Пример использования:

const interactiveElements = ally.get.query(document.body, node => node.tagName === 'BUTTON' && !node.disabled);
interactiveElements.forEach(el => console.log(el.node.id));

Ключевые моменты работы с ally.get

  1. Контексты поиска — почти все методы позволяют ограничивать область поиска конкретным узлом. Это ускоряет выполнение и позволяет работать с компонентами, а не с целым документом.
  2. Shadow DOM — методы корректно обрабатывают элементы внутри Shadow DOM, что критично для современных веб-компонентов.
  3. ARIA и CSS-скрытие — библиотека учитывает атрибуты aria-hidden и стили display: none, visibility: hidden, что позволяет точно определять доступные элементы.
  4. Фокус и табуляция — различие между focusable и tabbed помогает правильно управлять навигацией через клавиатуру.

Эти методы формируют основу для построения инструментов доступности, проверки интерфейсов и автоматизации тестов на соответствие стандартам WCAG. Они позволяют разработчикам создавать динамические, интерактивные и полностью доступные веб-приложения без необходимости вручную анализировать DOM.

Оглавление