Проблемы с z-index

Одной из наиболее частых проблем при использовании Intro.js является некорректное отображение подсказок и оверлеев из-за конфликтов с CSS-свойством z-index. Это особенно актуально в сложных веб-приложениях с большим количеством слоёв, модальных окон и кастомных компонентов.

Причины конфликтов

  1. Наследование z-index Элементы, к которым применяются подсказки Intro.js, могут находиться внутри контейнеров с заданным z-index. Поскольку Intro.js вставляет свои подсказки в конец body, они могут оказаться под другими элементами с высоким z-index.

  2. Статические и относительные контейнеры Контейнеры с позиционированием relative, absolute или fixed и установленным z-index создают новые контекстные слои. Если подсказка Intro.js не имеет достаточно высокий z-index, она будет перекрываться этими слоями.

  3. Модальные окна и сторонние библиотеки Использование сторонних UI-библиотек (например, для модальных окон) часто добавляет элементы с z-index > 1000. Intro.js по умолчанию использует z-index 9999, но конфликты могут возникать, если стили библиотеки перекрывают inline-стили Intro.js.

Структура подсказок и оверлеев

Intro.js создает следующие ключевые элементы:

  • .introjs-overlay – полупрозрачный фон вокруг выделяемого элемента.
  • .introjs-tooltip – подсказка с текстом и кнопками управления.
  • .introjs-helperLayer – рамка вокруг выделяемого элемента, управляющая подсветкой.

Каждый из этих элементов имеет свой z-index:

  • .introjs-overlay — 9998
  • .introjs-helperLayer — 9999
  • .introjs-tooltip — 10000

Эти значения могут быть переопределены через CSS или параметры конфигурации introJs().setOptions({}).

Настройка z-index через CSS

Для корректного отображения подсказок можно использовать переопределение стилей:

.introjs-overlay {
    z-index: 1050 !important;
}

.introjs-helperLayer {
    z-index: 1060 !important;
}

.introjs-tooltip {
    z-index: 1070 !important;
}

Важно: применять !important следует только при необходимости, чтобы перебить встроенные inline-стили Intro.js, которые по умолчанию имеют высокий приоритет.

Настройка через параметры Intro.js

Можно задать глобальный z-index через опцию overlayOpacity для прозрачного слоя и через CSS для подсказки:

introJs().setOptions({
    showStepNumbers: true,
    overlayOpacity: 0.7,
    tooltipClass: 'custom-intro-tooltip'
});
.custom-intro-tooltip {
    z-index: 1100 !important;
}

Особенности при работе с модальными окнами

Если подсказка должна появляться над модальным окном:

  1. Определить максимальный z-index модального окна.
  2. Установить для .introjs-tooltip и .introjs-helperLayer значение на 50–100 выше.

Пример:

.modal {
    z-index: 1050;
}

.introjs-helperLayer {
    z-index: 1100 !important;
}

.introjs-tooltip {
    z-index: 1110 !important;
}

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

Проверка проблем с z-index

  1. Включить инспектор браузера и посмотреть слои DOM.
  2. Проверить текущие значения z-index для элементов модального окна, контейнеров и подсказок.
  3. При необходимости увеличить z-index подсказки и оверлея Intro.js на несколько уровней выше всех конкурирующих элементов.

Рекомендации

  • Всегда задавать уникальные классы для подсказок, если приложение использует сторонние UI-библиотеки с собственными z-index.
  • Не изменять z-index слишком высоко без нужды, чтобы не нарушить порядок отображения других элементов.
  • Проверять отображение на мобильных устройствах, где контексты z-index могут отличаться из-за адаптивного CSS.

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

Оглавление