includeContainer

tabbable — это специализированная библиотека для определения элементов на странице, которые могут получать фокус через клавишу Tab. Она играет ключевую роль при создании доступных интерфейсов, управлении модальными окнами, меню и кастомными компонентами. Библиотека учитывает атрибуты tabindex, видимость элемента, а также его состояние (disabled, hidden).

Импорт и базовое использование

Подключение библиотеки в проект:

import { tabbable } from 'tabbable';

// Получение всех табулируемых элементов внутри контейнера
const container = document.querySelector('#my-container');
const focusableElements = tabbable(container);

console.log(focusableElements);
  • Функция tabbable() принимает один аргумент — контейнер, в пределах которого будет выполняться поиск.
  • Если контейнер не передан, будет использоваться document.body.
  • Возвращается массив DOM-элементов, упорядоченных по порядку табуляции.

Атрибут tabindex и его влияние

tabindex контролирует порядок фокусировки:

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

tabbable учитывает эти значения при формировании списка элементов. Элементы с отрицательным tabindex исключаются из итогового массива.

Видимость и доступность элементов

Библиотека проверяет:

  • display: none или visibility: hidden — элементы исключаются.
  • Родительский элемент с display: none также делает дочерние элементы недоступными для табуляции.
  • Актуальное состояние атрибута disabled на элементах формы.
const focusable = tabbable(container).filter(el => !el.disabled && el.offsetParent !== null);

Включение контейнера в поиск (includeContainer)

Ключевая опция includeContainer позволяет включить сам контейнер в список табулируемых элементов, если он удовлетворяет условиям фокусировки:

import { tabbable } from 'tabbable';

const container = document.querySelector('#modal');
const focusableElements = tabbable(container, { includeContainer: true });

console.log(focusableElements);
  • includeContainer: true — если контейнер сам может быть фокусирован, он будет добавлен в начало массива.
  • Полезно для кастомных модальных окон и интерактивных блоков, где контейнер выполняет роль интерактивного элемента.
  • При includeContainer: false (по умолчанию) проверка распространяется только на дочерние элементы.

Пример сценария: модальное окно с фокусируемым контейнером

const modal = document.querySelector('#modal');
const elements = tabbable(modal, { includeContainer: true });
console.log(elements); // ['#modal', кнопка 'Сохранить', кнопка 'Отмена']

Работа с кастомными компонентами

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

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

Производительность и оптимизация

При больших деревьях DOM важно учитывать:

  • Ограничение поиска конкретным контейнером.
  • Использование includeContainer только там, где это реально необходимо.
  • Избегание повторного вызова tabbable() без изменений структуры DOM.
const modalElements = tabbable(modal, { includeContainer: true });
// кэширование элементов для повторного использования

Итоговые рекомендации по includeContainer

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