Возвращаемые значения

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

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

Основной метод: tabbable()

import { tabbable } from 'tabbable';

const elements = tabbable(container);
  • Возвращаемое значение: массив элементов HTMLElement.
  • Порядок элементов: слева направо и сверху вниз согласно визуальному расположению и стандартам HTML.
  • Фильтруемые элементы: кнопки, ссылки с href, элементы формы, элементы с tabindex >= 0.
  • Не включаются: элементы с display: none, visibility: hidden, disabled, tabindex="-1".

Разница между tabbable и focusable

Библиотека предоставляет отдельный метод focusable(), возвращающий элементы, которые могут быть сфокусированы, но не обязательно доступны через Tab:

import { focusable } from 'tabbable';

const focusableElements = focusable(container);
  • Возвращаемое значение: массив HTMLElement.
  • Отличие: включает элементы с отрицательным tabindex (например, tabindex="-1"), что позволяет программно устанавливать фокус.

Ключевой момент: все элементы, возвращаемые tabbable(), гарантированно можно достичь с помощью Tab, тогда как focusable() возвращает элементы, которые могут быть сфокусированы вручную через JavaScript.

Обработка атрибута tabindex

tabindex влияет на возвращаемые значения следующим образом:

  1. tabindex="-1" — элемент исключается из списка tabbable().
  2. tabindex="0" — элемент включается, позиция определяется естественным порядком документа.
  3. tabindex положительное (1 и выше) — элемент включается и перемещается в начало последовательности, в порядке возрастания значения.

Пример:

<button>Button 1</button>
<button tabindex="2">Button 2</button>
<button tabindex="1">Button 3</button>
const elements = tabbable(document.body);
// Порядок: Button 3, Button 2, Button 1

Фильтры возвращаемых значений

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

const elements = tabbable(container, { includeContainer: true });
  • includeContainer — если true, сам контейнер проверяется на tabbable и может быть включён в результат.
  • getShadowRoot — функция для поддержки веб-компонентов с Shadow DOM, позволяет рекурсивно собирать tabbable-элементы внутри Shadow DOM.

Пример с пользовательской фильтрацией:

const elements = tabbable(container, {
  includeContainer: false,
  filter: el => el.tagName !== 'INPUT'
});

Возвращаемый массив исключит все элементы <input>.

Особенности работы с динамическим DOM

Возвращаемый массив не является живым списком — изменения в DOM после вызова функции не обновляют массив автоматически. Если структура страницы изменяется (добавление или удаление элементов, изменение tabindex), нужно заново вызвать метод tabbable() для актуального списка.

Итоговые правила интерпретации возвращаемых значений

  • Всегда возвращается массив DOM-элементов.
  • Порядок соответствует визуальной и логической табуляции.
  • Фильтруются элементы с display: none, visibility: hidden, disabled и tabindex="-1".
  • Методы tabbable() и focusable() различаются по критериям включения элементов с отрицательным tabindex.
  • Для поддержки Shadow DOM и кастомных фильтров можно передавать опции.

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

Оглавление