Проблемы совместимости браузеров

Shepherd.js построен на базе современных возможностей браузеров, таких как Promises, ES6-классы, и CSS-переходы. Это накладывает определённые ограничения на поддержку старых версий браузеров. Основные совместимые платформы включают последние версии Chrome, Firefox, Safari, Edge и мобильные браузеры на основе Chromium.

Для старых браузеров, например Internet Explorer 11 и ниже, функциональность Shepherd.js может быть ограничена или полностью недоступна, так как библиотека использует ES6-синтаксис и API, которые отсутствуют в этих версиях. Использование полифиллов может частично решить проблему, но не гарантирует полную корректную работу интерактивных подсказок и анимаций.

Проблемы с мобильными браузерами

На мобильных устройствах особое внимание стоит уделить адаптивности и позиционированию подсказок. Shepherd.js рассчитывает позицию подсказок относительно элемента, к которому они привязаны, используя getBoundingClientRect(). На мобильных устройствах с динамическим изменением размеров окна (например, при появлении клавиатуры) подсказки могут смещаться или становиться частично невидимыми.

Решения включают:

  • Использование события window.resize для пересчёта позиции подсказок.
  • Ограничение высоты и ширины подсказок с помощью CSS для предотвращения выхода за границы экрана.
  • Включение scrollTo для автоматического прокручивания страницы к целевому элементу перед отображением подсказки.

Проблемы с z-index и перекрытием

Shepherd.js создаёт подсказки, которые динамически добавляются в DOM, обычно в конец <body>. В сложных приложениях с многослойными элементами, модальными окнами или сторонними библиотеками, может возникнуть ситуация, когда подсказка перекрывается другими элементами.

Способы решения:

  • Явно задавать z-index для контейнера Shepherd через defaultStepOptions:
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true,
    modalOverlayOpeningPadding: 5,
    useModalOverlay: true,
    zIndex: 10000
  }
});
  • Проверка CSS сторонних библиотек на наличие position: relative или overflow: hidden, влияющих на визуализацию подсказок.

Анимации и производительность

Shepherd.js использует CSS-анимации для появления и скрытия подсказок. В браузерах с ограниченной поддержкой CSS-переходов анимации могут не воспроизводиться или быть прерывистыми. Кроме того, при работе на слабых устройствах большое количество шагов с интенсивной анимацией может влиять на плавность прокрутки страницы.

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

  • Минимизировать количество сложных анимаций одновременно.
  • Проверять производительность на целевых мобильных устройствах.
  • Использовать статические подсказки без анимации в случаях, когда производительность критична.

Особенности работы с Shadow DOM

Если элементы, к которым привязываются подсказки, находятся внутри Shadow DOM, Shepherd.js может не корректно вычислять их позицию, так как getBoundingClientRect() возвращает координаты относительно внешнего документа, не учитывая вложенность Shadow DOM.

Возможные подходы:

  • Программно передавать позицию элемента через пользовательские коллбэки в шаге:
tour.addStep({
  text: 'Пример для Shadow DOM',
  attachTo: {
    element: shadowRoot.querySelector('#button'),
    on: 'bottom'
  }
});
  • В некоторых случаях требуется создание обёртки элемента в основном DOM для корректного позиционирования.

Стилизация и темы

Shepherd.js поддерживает кастомизацию через темы и CSS-классы. Однако разные браузеры могут интерпретировать CSS по-разному: тени, градиенты, border-radius и шрифты могут визуально отличаться. Для унификации рекомендуется использовать normalize.css или аналогичные подходы, а также проверять отображение подсказок на всех целевых платформах.

Поддержка событий

Shepherd.js генерирует события, такие как show, hide, complete, cancel. В некоторых браузерах с ограниченной поддержкой событий DOM3 могут возникнуть проблемы с делегированными событиями, особенно если используется динамическое создание шагов после инициализации тура. Решение — всегда подписываться на события после создания шагов и использовать нативные addEventListener вместо сторонних библиотек, которые могут по-разному обрабатывать события на разных браузерах.

Итоговые рекомендации

  • Проверять работу на последних версиях браузеров, включая мобильные.
  • Использовать полифиллы для ES6-функций в старых браузерах.
  • Учитывать особенности Shadow DOM и модальных окон.
  • Настраивать z-index и CSS для корректного отображения.
  • Тестировать производительность на слабых устройствах и оптимизировать анимации.
  • Использовать CSS reset/normalize для минимизации визуальных различий.

Правильное понимание этих нюансов позволяет обеспечить стабильную работу Shepherd.js во всех поддерживаемых браузерах и устройствах.

Оглавление