Переход с более ранних версий

Библиотека Focus-trap в JavaScript предназначена для управления фокусом внутри модальных окон, всплывающих панелей и других интерактивных областей. Основная задача — предотвратить выход фокуса за пределы контейнера, пока активен «трап» (trap). Это критично для обеспечения доступности (accessibility) и корректной работы клавиатурной навигации.

Focus-trap работает по принципу замыкания фокуса: при попытке перемещения клавишей Tab или Shift+Tab фокус циклично возвращается к элементам внутри контейнера.

Инициализация и базовое использование

Создание трапа осуществляется через функцию createFocusTrap, которая принимает два параметра:

import { createFocusTrap } from 'focus-trap';

const modal = document.getElementById('modal');

const trap = createFocusTrap(modal, {
  initialFocus: modal.querySelector('input'),
  escapeDeactivates: true,
  clickOutsideDeactivates: false,
});

Ключевые параметры:

  • initialFocus — элемент, который получает фокус при активации трапа.
  • escapeDeactivates — разрешает закрытие трапа клавишей Escape.
  • clickOutsideDeactivates — определяет, может ли клик вне контейнера деактивировать трап.

Активация и деактивация трапа выполняются методами trap.activate() и trap.deactivate(). При деактивации фокус возвращается на элемент, который был активен до активации.

Новые возможности и изменения в последних версиях

В последних версиях Focus-trap появились следующие ключевые изменения по сравнению с ранними версиями:

  1. Поддержка асинхронной инициализации Теперь можно задавать initialFocus через функцию, возвращающую элемент или промис:

    const trap = createFocusTrap(modal, {
  initialFocus: () => document.querySelector('#async-input')
});

  2. Обновлённая обработка событий клика вне контейнера Ранее clickOutsideDeactivates просто отключал трап. Сейчас добавлена возможность передавать функцию для более гибкой логики:

    clickOutsideDeactivates: (event) => !event.target.closest('.no-deactivate')

  3. Поддержка вложенных трапов В новых версиях можно безопасно использовать несколько трапов внутри одного документа, при этом внутренний трап корректно захватывает фокус, не мешая внешнему.

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

    returnFocusOnDeactivate: document.getElementById('open-button')

Работа с динамическим контентом

Focus-trap корректно обрабатывает динамически добавляемые элементы. Для этого необходимо вызвать метод updateContainerElements() после изменения содержимого контейнера:

trap.updateContainerElements();

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

Интеграция с фреймворками

Для React, Vue или Angular рекомендуется инициализация трапа в момент монтирования компонента, с последующей деактивацией при размонтировании. Пример для React:

useEffect(() => {
  const trap = createFocusTrap(modalRef.current);
  trap.activate();
  return () => trap.deactivate();
}, []);

Для динамически рендерящихся модальных окон важно учитывать, что контейнер должен существовать в DOM до активации трапа.

Расширенные опции и обработчики

Focus-trap поддерживает дополнительные опции:

  • allowOutsideClick — разрешает клики вне трапа без деактивации.
  • tabbableOptions — передаёт настройки библиотеке tabbable для управления видимостью и доступностью элементов.
  • onActivate и onDeactivate — коллбэки, вызываемые при активации и деактивации трапа.

Пример:

const trap = createFocusTrap(modal, {
  onActivate: () => console.log('Trap activated'),
  onDeactivate: () => console.log('Trap deactivated'),
  allowOutsideClick: true
});

Отличия от более ранних версий

  • Ранее initialFocus не поддерживал функции и промисы, что ограничивало динамические сценарии.
  • Обработка кликов вне контейнера была менее гибкой, и часто требовала обертки в кастомный код.
  • Вложенные трапы в старых версиях могли конфликтовать и нарушать цикл фокуса.
  • Новая версия оптимизирует производительность за счет уменьшения количества глобальных слушателей событий.

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

  • Всегда указывать initialFocus, чтобы улучшить доступность.
  • Использовать escapeDeactivates для модальных окон.
  • Для вложенных модальных окон применять отдельные трапы с корректной инициализацией и деактивацией.
  • После изменения DOM внутри трапа вызывать updateContainerElements().
  • Настраивать returnFocusOnDeactivate для управления пользовательским опытом при закрытии модальных окон.

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

Оглавление