ally.query.focusable

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

Основное назначение

ally.query.focusable позволяет определить все элементы, которые могут быть:

  • доступны через клавиатуру,
  • получить фокус программно через element.focus(),
  • учтены при навигации с использованием табуляции.

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

Сигнатура метода

ally.query.focusable(root?, options?)
  • root — корневой элемент, внутри которого осуществляется поиск фокусируемых элементов. Если не указан, поиск производится по всему документу (document).
  • options — объект конфигурации, позволяющий уточнять условия поиска.

Параметры options

Основные опции:

  • includeOnlyTabbable (boolean) — возвращает только элементы, которые входят в последовательность табуляции (tabindex !== -1).

  • context (Element) — альтернативный корневой элемент, внутри которого будет производиться поиск.

  • filter (Function) — функция, принимающая элемент и возвращающая true, если элемент следует включить в результат. Позволяет фильтровать элементы по любым дополнительным критериям.

  • strategy (string) — метод проверки видимости:

    • "strict" — элемент считается видимым только если полностью видим.
    • "all" — включает элементы с частичной видимостью.

Пример:

const focusableElements = ally.query.focusable(document.body, {
  includeOnlyTabbable: true,
  strategy: 'strict'
});

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

Принципы работы

Метод проверяет несколько ключевых свойств элементов:

  1. HTML-теги и атрибуты Элементы типа <a href>, <button>, <input>, <textarea>, <select> и [tabindex] по умолчанию являются потенциально фокусируемыми.

  2. Состояние видимости Элементы с display: none, visibility: hidden или находящиеся внутри невидимых контейнеров исключаются.

  3. Атрибут tabindex

    • tabindex="0" — элемент доступен для табуляции в естественном порядке.
    • tabindex="-1" — элемент можно сфокусировать программно, но не через клавишу Tab.
    • tabindex>0 — задает пользовательский порядок табуляции.

  4. Отключенные элементы Элементы с атрибутом disabled исключаются из списка фокусируемых.

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

Выделение всех фокусируемых элементов внутри модального окна:

const modal = document.querySelector('.modal');
const focusableElements = ally.query.focusable(modal);

console.log(focusableElements);

Фильтрация только интерактивных кнопок:

const buttons = ally.query.focusable(document, {
  filter: el => el.tagName === 'BUTTON'
});

Поиск элементов, доступных для табуляции, с учетом частичной видимости:

const tabbableElements = ally.query.focusable(document, {
  includeOnlyTabbable: true,
  strategy: 'all'
});

Связь с другими методами ally.js

  • ally.query.tabbable — возвращает только элементы, которые входят в последовательность табуляции.
  • ally.query.firstTabbable / ally.query.lastTabbable — позволяют быстро определить первый или последний элемент в логике табуляции.
  • ally.is.focusable — проверяет отдельный элемент на возможность получения фокуса.

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

Особенности и нюансы

  • Динамические изменения DOM: метод всегда актуален при каждом вызове, так как пересчитывает состояние элементов в момент вызова.
  • Shadow DOM: для поиска внутри Shadow DOM необходимо передать корневой элемент shadow root в качестве root.
  • Скрытые или удалённые элементы: метод учитывает стили и атрибуты, исключая элементы, которые не видны на экране.
  • Производительность: при больших деревьях DOM рекомендуется ограничивать область поиска корневым элементом вместо всего документа.

Практическое применение

  • Реализация модальных окон с правильной фокусной навигацией.
  • Автоматическая установка фокуса на первый интерактивный элемент при открытии панели.
  • Управление доступностью сложных форм и виджетов.
  • Тестирование интерфейсов на соответствие стандартам доступности (WCAG).

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

Оглавление