FocusTrap

Концепция

FocusTrap — это вспомогательный компонент, который:

• Зацикливает фокус — при нажатии Tab на последнем интерактивном элементе фокус переходит на первый, а при Shift + Tab на первом — на последний;
• Автоматически устанавливает фокус — при появлении области может автоматически установить фокус на первый интерактивный элемент или на корневой элемент;
• Восстанавливает фокус — при закрытии области возвращает фокус на элемент, который был в фокусе до открытия.

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

FocusTrap широко используется внутри VKUI для компонентов модальных окон и всплывающих элементов:

• ModalCard
• ModalPage
• Alert
• ActionSheet
• Popover
• OnboardingTooltip
• DateInput

Базовый пример

Для использования FocusTrap необходимо:

1. Создать ref для корневого элемента области;
2. Передать этот ref в свойство rootRef компонента FocusTrap;
3. Передать этот же ref на корневой элемент контента;
4. Добавить tabIndex={-1} на корневой элемент для возможности программной фокусировки.

Автофокус

Свойство autoFocus управляет поведением автоматической установки фокуса при появлении области.

autoFocus={true} (по умолчанию)

Фокус автоматически устанавливается на первый интерактивный элемент внутри области.

autoFocus="root"

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

autoFocus={false}

Автофокус отключён. Используйте, когда фокус уже находится внутри области или управляется вручную.

Восстановление фокуса

Свойство restoreFocus управляет возвратом фокуса на предыдущий элемент при закрытии области.

• true (по умолчанию) — фокус возвращается на элемент, который был в фокусе до открытия области;
• false — фокус не возвращается;
• () => boolean | HTMLElement — функция, которая возвращает boolean или конкретный элемент для фокуса.

Отключение захвата фокуса

Свойство disabled позволяет временно отключить захват фокуса.

Задержка автофокуса

Свойство autoFocusDelay позволяет задать задержку в миллисекундах перед автофокусом. Это полезно при использовании с анимациями, когда нужно дождаться завершения анимации появления.

<FocusTrap rootRef={focusTrapRef} autoFocusDelay={300}>
  {/* ... */}
</FocusTrap>

Рекомендации по использованию

Когда использовать FocusTrap

• Модальные окна и диалоги — фокус должен оставаться внутри модального окна, пока оно открыто;
• Всплывающие меню — пользователь должен иметь возможность навигироваться по пунктам меню с помощью клавиатуры;
• Формы в выпадающих панелях — например, календарь в DateInput.

Когда НЕ использовать FocusTrap

• Для обычных секций страницы — захват фокуса не нужен для стандартной навигации;
• Для тултипов с текстовым содержимым — если тултип не содержит интерактивных элементов, используйте свойство disableFocusTrap в компонентах типа Tooltip.

Доступность (a11y)

При использовании FocusTrap для модальных окон не забывайте:

1. Добавлять role="dialog" и aria-modal="true" на корневой элемент;
2. Указывать aria-label или aria-labelledby для описания содержимого;
3. Обеспечивать закрытие по клавише Escape.

<FocusTrap rootRef={focusTrapRef}>
  <div
    ref={focusTrapRef}
    tabIndex={-1}
    role="dialog"
    aria-modal="true"
    aria-label="Название диалога"
  >
    {/* Содержимое */}
  </div>
</FocusTrap>

Свойства и методы