Установка и подключение

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

Установка через npm и yarn

Для интеграции библиотеки в проект на JavaScript или TypeScript применяется стандартная установка через пакетный менеджер:

npm install focus-trap

или

yarn add focus-trap

После установки пакет становится доступен для импорта в модульной структуре проекта.

Подключение в модульной системе

Для использования в ES-модулях применяется следующий синтаксис:

import { createFocusTrap } from 'focus-trap';

В случае CommonJS:

const { createFocusTrap } = require('focus-trap');

Библиотека предоставляет функцию createFocusTrap, создающую объект фокус-трапа для указанного контейнера.

Подключение через CDN

Для проектов, где не используется пакетный менеджер, возможно подключение через CDN. Рекомендуется использовать unpkg или jsDelivr:

<script src="https://unpkg.com/focus-trap/dist/focus-trap.umd.js"></script>
<script>
  const focusTrap = focusTrapFactory.createFocusTrap('#modal');
</script>

При подключении через CDN объект создается с помощью глобальной функции focusTrapFactory.createFocusTrap, доступной в window.

Инициализация фокус-трапа

После подключения библиотеки требуется создать экземпляр фокус-трапа для конкретного контейнера:

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

const trap = createFocusTrap(modal, {
  escapeDeactivates: true,
  clickOutsideDeactivates: true,
  initialFocus: '#modal input:first-child',
  fallbackFocus: '#modal'
});

Пояснения параметров:

escapeDeactivates – при нажатии клавиши Esc трап деактивируется.
clickOutsideDeactivates – клик за пределами контейнера отключает фокус-трап.
initialFocus – элемент, на который будет установлен фокус при активации.
fallbackFocus – элемент для фокусировки, если initialFocus отсутствует или не найден.

Активация и деактивация

После создания экземпляра фокус-трапа его необходимо активировать:

trap.activate();

Для временного отключения или полного завершения работы:

trap.deactivate();

Методы activate и deactivate позволяют динамически управлять фокусом при открытии и закрытии модальных элементов.

Особенности подключения и использования

Совместимость с динамическим контентом: если контейнер или элементы появляются в DOM после инициализации, рекомендуется пересоздавать или обновлять фокус-трап.
Селекторы элементов: initialFocus и fallbackFocus поддерживают CSS-селекторы или прямые DOM-элементы.
Поддержка нескольких трапов: библиотека допускает одновременное существование нескольких фокус-трапов, однако одновременно активным может быть только один.

Примеры интеграции

Простая модалка:

const modal = document.getElementById('modal');
const openButton = document.getElementById('open-modal');
const closeButton = document.getElementById('close-modal');

const trap = createFocusTrap(modal, {
  escapeDeactivates: true,
  clickOutsideDeactivates: true
});

openButton.addEventListener('click', () => {
  modal.style.display = 'block';
  trap.activate();
});

closeButton.addEventListener('click', () => {
  trap.deactivate();
  modal.style.display = 'none';
});

Фокус на первом элементе формы:

const trap = createFocusTrap('#form-modal', {
  initialFocus: '#form-modal input[name="username"]',
  fallbackFocus: '#form-modal'
});