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

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

Методы ally.query

Методы ally.query делятся на несколько категорий: поиск интерактивных элементов, фильтрация по состояниям и роли, управление фокусом и анализ видимости. Каждый метод возвращает массив объектов DOM-элементов или объект с информацией о состоянии элемента.

1. query.firstTabbable()

Возвращает первый элемент на странице, доступный для фокусировки с клавиатуры (tabbable). Используется для определения стартовой точки навигации по клавишам Tab.

Сигнатура:

ally.query.firstTabbable([context])
  • context — DOM-элемент, внутри которого происходит поиск. Если не указан, поиск производится по всему документу.

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

  • Игнорирует скрытые и disabled элементы.
  • Учитывает tabindex и элементы с contenteditable.

2. query.lastTabbable()

Возвращает последний tabbable-элемент в указанном контексте.

Применение:

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

3. query.allTabbable()

Возвращает массив всех tabbable-элементов в указанном контексте.

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

const tabbables = ally.query.allTabbable(document.body);
tabbables.forEach(el => console.log(el));

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

  • Можно комбинировать с фильтрацией по ролям или состояниям.
  • Включает элементы, доступные через клавишу Tab, но исключает элементы с display: none или aria-hidden="true".

4. query.focusable()

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

Разница с tabbable:

  • focusable включает элементы, доступные через скрипты (element.focus()), даже если они не участвуют в таб-цикле.

5. query.firstFocus()

Возвращает первый focusable элемент в контексте. Отличается от firstTabbable тем, что учитывает все focusable элементы, а не только tabbable.

6. query.lastFocus()

Возвращает последний focusable элемент в указанном контексте.

7. query.allFocusable()

Возвращает массив всех focusable элементов. Полезно для анализа всей страницы или модальных контейнеров с точки зрения доступности.

8. query.visible()

Позволяет выбрать только видимые элементы.

Сигнатура:

ally.query.visible(elements)
  • elements — массив DOM-элементов или NodeList.

Применение:

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

Критерии видимости:

  • Элемент должен иметь ненулевой размер (offsetWidth/offsetHeight).
  • Элемент не должен быть скрыт через CSS (display: none, visibility: hidden).
  • Учитывает родительские элементы: если контейнер скрыт, элемент также считается невидимым.

9. query.tabbable()

Возвращает все элементы, доступные через клавишу Tab с учётом порядка табуляции. Отличается от allFocusable строгим соответствием правилам табуляции и порядку в DOM.

Параметры:

  • context — контейнер для поиска.
  • includeContext — флаг, включать ли сам контейнер, если он tabbable.

10. query.tabbableExcept({context, except})

Возвращает tabbable элементы за исключением указанных. Используется при реализации обхода по клавишам в модальных диалогах, когда нужно исключить элементы родительского контейнера.

Пример:

ally.query.tabbableExcept({
  context: modal,
  except: [closeButton]
});

11. query.first({filter})

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

Параметры фильтрации:

  • filter.visible — учитывать только видимые элементы.
  • filter.tabbable — учитывать только tabbable элементы.
  • filter.focusable — учитывать focusable элементы.

12. query.all({filter})

Возвращает массив всех элементов, подходящих под заданный фильтр. Может объединять несколько критериев: видимость, tabbable, роль.

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

ally.query.all({
  context: form,
  filter: { tabbable: true, visible: true }
});

13. query.isFocusable(element)

Возвращает true, если элемент может получить фокус, иначе false.

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

  • Проверяет CSS-свойства и атрибуты (disabled, tabindex, aria-hidden).
  • Учитывает родительские контейнеры, скрывающие элемент.

14. query.isTabbable(element)

Возвращает true, если элемент доступен через клавишу Tab.

Применение:

  • Проверка корректности порядка табуляции в интерфейсе.
  • Автоматизированные тесты доступности.

15. query.closestTabbable(element)

Возвращает ближайший tabbable элемент относительно заданного. Используется для корректного управления фокусом при динамических изменениях DOM.

16. query.nextTabbable(element)

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

17. query.previousTabbable(element)

Возвращает предыдущий tabbable элемент. Работает в связке с nextTabbable для обхода фокусируемых элементов вперед и назад.

18. query.allTabbableExcept(exceptList)

Возвращает все tabbable элементы за исключением указанных. Позволяет создавать исключающие правила для модальных окон или динамических компонентов.

19. query.within(context)

Фильтрует элементы, находящиеся внутри указанного контейнера. Может применяться к результатам других методов:

const tabbablesInModal = ally.query.tabbable().within(modal);

20. query.ignored()

Возвращает элементы, которые игнорируются при навигации и фокусировке по умолчанию. Это элементы с aria-hidden="true", скрытые через CSS или с tabindex="-1".

Методы ally.query обеспечивают полный контроль над элементами интерфейса с точки зрения доступности, позволяют строить сложные цепочки фильтрации и навигации, обеспечивая корректное взаимодействие с пользователем. Комбинирование этих методов позволяет реализовывать модальные окна, кастомные компоненты и формы с правильной последовательностью фокуса, минимизируя риски недоступности интерфейса для пользователей с ограничениями.

Оглавление