Настройка z-index

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

Основные принципы работы z-index в Shepherd.js

  • Слои тултипов – каждый шаг тура создаёт свой DOM-элемент с классом .shepherd-step, который позиционируется поверх контента страницы. Его значение z-index по умолчанию равно 1000.
  • Оверлей – элемент .shepherd-modal-overlay-container используется для затемнения фона при модальном туре. Его z-index по умолчанию выше, чем у стандартного шага (обычно 2000), чтобы перекрывать интерактивные элементы страницы.
  • Контейнер тура – .shepherd-content наследует z-index от шага и может быть дополнительно настроен через CSS или опции Shepherd.

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

Настройка через опции шага

Shepherd.js позволяет задать z-index индивидуально для каждого шага через свойство attachTo и CSS-классы:

const tour = new Shepherd.Tour({
  useModalOverlay: true,
  defaultStepOptions: {
    classes: 'custom-step',
    scrollTo: { beh * avior: 'smooth', block: 'center' },
  }
});

tour.addStep({
  id: 'example-step',
  text: 'Пример шага с кастомным z-index',
  attachTo: { element: '.target-element', on: 'bottom' },
  classes: 'custom-z-index',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

tour.start();

В CSS можно задать конкретное значение z-index:

.custom-z-index {
  z-index: 3000 !important;
}

Использование !important рекомендуется только в случае конфликта с другими слоями, поскольку Shepherd.js динамически управляет стилями через встроенные классы.

Глобальная настройка z-index

Для единообразного управления всеми шагами тура можно использовать defaultStepOptions.classes с общим классом и задать z-index через CSS:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'global-z-index',
    scrollTo: true
  }
});
.global-z-index {
  z-index: 1500;
}

Это позволяет избежать повторного назначения z-index для каждого шага.

Управление z-index для оверлея

Если используется модальный оверлей (useModalOverlay: true), значение z-index оверлея задается отдельным классом .shepherd-modal-overlay-container. По умолчанию его z-index выше, чем у шагов, что гарантирует блокировку взаимодействия с элементами страницы:

.shepherd-modal-overlay-container {
  z-index: 2500;
}

Важно учитывать, что шаги должны иметь z-index меньше оверлея, иначе часть контента тура может оказаться скрытой за модальным фоном.

Динамическая корректировка z-index

Для сложных интерфейсов можно изменять z-index на лету через события Shepherd:

tour.on('show', function(step) {
  const stepElement = step.el;
  stepElement.style.zIndex = 3500;
});

Это позволяет контролировать порядок отображения при перекрытии сторонних всплывающих окон или меню с высоким z-index.

Рекомендации по управлению слоями

  1. Определять приоритет слоев: сначала оверлей, затем шаги, затем кастомные всплывающие элементы.
  2. Использовать классы для групп шагов: удобно изменять z-index для целой группы шагов сразу.
  3. Избегать конфликтов с глобальными стилями: проверять, не перекрывают ли сторонние тултипы шаги тура.
  4. Динамическая корректировка: события show, hide и active позволяют изменять z-index в зависимости от состояния страницы.

Пример комплексной конфигурации

const tour = new Shepherd.Tour({
  useModalOverlay: true,
  defaultStepOptions: {
    classes: 'tour-step-global',
    scrollTo: true
  }
});

tour.addStep({
  id: 'first',
  text: 'Первый шаг',
  attachTo: { element: '.first-target', on: 'top' }
});

tour.addStep({
  id: 'second',
  text: 'Второй шаг с более высоким z-index',
  attachTo: { element: '.second-target', on: 'bottom' },
  classes: 'tour-step-global high-z-index'
});
.tour-step-global {
  z-index: 1500;
}

.high-z-index {
  z-index: 3000;
}

.shepherd-modal-overlay-container {
  z-index: 2500;
}

Такой подход обеспечивает предсказуемое поведение всех элементов тура вне зависимости от структуры страницы и сторонних модальных окон.

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

Оглавление