Обратная совместимость

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

Поддержка старых версий браузеров

Shepherd.js построен на современном JavaScript с использованием ES6+ синтаксиса, однако для обеспечения обратной совместимости с более старыми браузерами можно использовать транспилеры (например, Babel). Основные моменты:

Использование полифиллов для методов Promise, Array.from, Object.assign и других, которые отсутствуют в старых версиях браузеров.
Проверка поддержки CSS-перемещений и flexbox, так как позиционирование тултипов зависит от этих свойств.
В некоторых старых версиях Safari и IE11 наблюдаются проблемы с анимациями и обработкой событий клика, что требует дополнительной отладки.

Совместимость API

API Shepherd.js развивается от версии к версии, и некоторые методы или параметры могут быть изменены или устаревшими. Чтобы обеспечить обратную совместимость:

Использовать устаревшие методы с учетом документации. Например, в версии 8.x метод addStep поддерживает как объект настроек шага, так и отдельные свойства title, text, attachTo. В новых версиях предпочтительнее объектная форма, но старая все еще поддерживается.
Проверять наличие новых обязательных полей. Например, начиная с версии 9.x, поле id для шага стало рекомендованным, чтобы обеспечить точную идентификацию шага при динамическом управлении туром.
Сохранять старые обработчики событий через on и off. Хотя введены новые методы once или emit, старые методы не удалены и продолжают работать для обратной совместимости.

Совместимость с CSS

Shepherd.js использует кастомные классы и тему default для оформления подсказок. Для обратной совместимости:

Изменения в классе .shepherd-element должны учитывать старые стили. Например, новые версии добавляют классы .shepherd-modal-overlay, что может влиять на z-index.
Стили для анимаций (shepherd-show, shepherd-hide) должны корректно работать со старыми браузерами. Если используется кастомная анимация, стоит проверить, что она не конфликтует с базовыми классами библиотеки.
Для старых проектов желательно сохранять оригинальные CSS-классы, чтобы новые версии библиотеки не ломали визуальный интерфейс.

Работа с Popper.js

Shepherd.js опирается на Popper.js для позиционирования шагов. Обновления Popper.js иногда меняют API, поэтому обратная совместимость требует:

Проверки версии Popper.js. Shepherd.js версии 9.x требует Popper.js 2.x, тогда как версии 8.x работали с Popper.js 1.x. При обновлении необходимо либо использовать совместимую версию Popper.js, либо адаптировать конфигурацию позиционирования.
Использования свойств attachTo и popperOptions для точной настройки позиции подсказки. Старый синтаксис { element, on } продолжает поддерживаться, но расширенные возможности требуют нового API.

Заключение по обратной совместимости

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

Использование подхода постепенной миграции, сохранение старого API и тщательное тестирование позволяют минимизировать риски при переходе на новые версии Shepherd.js и обеспечивают непрерывность пользовательского опыта.