Настройка через useModalOverlay

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

Подключение и базовая инициализация

Для использования useModalOverlay необходимо импортировать его из Shepherd:

import { ShepherdTour, useModalOverlay } from 'shepherd.js';

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

const tour = new ShepherdTour({
  defaultStepOptions: {
    cancelIcon: {
      enabled: true
    },
    scrollTo: { beh * avior: 'smooth', block: 'center' }
  },
  useModalOverlay: true
});

Включение useModalOverlay: true автоматически активирует затемнение фона и добавляет возможность клика по оверлею для закрытия шага.

Создание оверлея с кастомными настройками

useModalOverlay позволяет управлять поведением оверлея через дополнительные параметры. Основные опции:

  • className — CSS-класс для кастомизации стиля оверлея.
  • clickOutsideToClose — закрытие шага при клике вне активного элемента.
  • escapeToClose — возможность закрытия оверлея через клавишу Escape.
  • canClickTarget — позволяет пользователю взаимодействовать с элементами под оверлеем.

Пример настройки:

tour.useModalOverlay({
  className: 'custom-overlay',
  clickOutsideToClose: true,
  escapeToClose: true,
  canClickTarget: false
});

В этом примере создаётся затемнение с кастомным CSS-классом custom-overlay, шаг закрывается при клике вне выделенного элемента, но взаимодействие с элементами под оверлеем запрещено.

Динамическое управление оверлеем на шагах

Каждый шаг тура можно настроить отдельно, включая управление оверлеем:

tour.addStep({
  id: 'example-step',
  text: 'Этот шаг демонстрирует работу модального оверлея.',
  attachTo: {
    element: '.target-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Next',
      action: tour.next
    }
  ],
  useModalOverlay: true
});

Включение useModalOverlay на уровне шага позволяет показывать оверлей только для конкретного шага, что полезно при сложных турах с несколькими сценариями.

Кастомизация стиля через CSS

Для полного контроля внешнего вида оверлея используется CSS. Основные элементы:

.shepherd-modal-overlay-container {
  background-color: rgba(0, 0, 0, 0.7);
  transition: opacity 0.3s ease-in-out;
}

.custom-overlay {
  background-color: rgba(50, 50, 50, 0.6);
  border-radius: 8px;
}
  • .shepherd-modal-overlay-container — стандартный контейнер оверлея.
  • .custom-overlay — класс, переданный в параметре className.

Использование CSS-переопределений позволяет контролировать прозрачность, цвет, тени и анимацию появления.

Управление взаимодействием с элементами под оверлеем

Параметр canClickTarget определяет, будут ли элементы под оверлеем интерактивными:

tour.useModalOverlay({
  canClickTarget: true
});
  • true — позволяет взаимодействовать с кнопками и ссылками под затемнением.
  • false — блокирует любые клики, обеспечивая полный фокус на шаге тура.

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

Динамическое включение и отключение оверлея

useModalOverlay можно активировать и деактивировать в ходе выполнения тура:

const overlay = tour.useModalOverlay();

overlay.show(); // Показать оверлей
overlay.hide(); // Скрыть оверлей

Это удобно для сложных сценариев, где шаги с оверлеем чередуются с обычными шагами без затемнения.

Анимация и плавное появление

Для плавного отображения оверлея можно использовать CSS-переходы и добавить класс shepherd-modal-overlay-fade:

.shepherd-modal-overlay-fade {
  opacity: 0;
  transition: opacity 0.5s ease;
}

.shepherd-modal-overlay-fade.shepherd-modal-overlay-container--visible {
  opacity: 1;
}
  • .shepherd-modal-overlay-container--visible добавляется автоматически при показе оверлея.
  • Плавная анимация улучшает пользовательский опыт, делая тур визуально привлекательным.

Работа с несколькими оверлеями

Shepherd.js поддерживает один активный оверлей за раз. Для имитации нескольких слоёв создаются кастомные элементы поверх основного оверлея, но при этом следует учитывать z-index и блокировку кликов:

const extraOverlay = document.createElement('div');
extraOverlay.classList.add('extra-overlay');
document.body.appendChild(extraOverlay);

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

Практические советы по useModalOverlay

  • Использовать clickOutsideToClose только на простых шагах, чтобы случайные клики не прерывали сложный сценарий.
  • Настраивать прозрачность оверлея через CSS для гармоничного визуального выделения активного элемента.
  • При многократном использовании динамически показывать и скрывать оверлей вместо постоянного включения на всех шагах, чтобы экономить ресурсы и улучшить UX.
  • Совмещать canClickTarget с шагами, где пользователю нужно взаимодействовать с формами или кнопками.

useModalOverlay — мощный инструмент для полного контроля над визуальной презентацией шагов в Shepherd.js. Его гибкость позволяет создавать как простые затемнённые подсказки, так и сложные интерактивные туры с кастомными эффектами и точным управлением поведением пользователя.

Оглавление