Breaking changes

Driver.js — это мощная библиотека для создания интерактивных пошаговых руководств в веб-приложениях. Понимание breaking changes критично для поддержки проектов, особенно при обновлении с одной версии библиотеки на другую. Разберём ключевые изменения, которые могут повлиять на существующий код.

Изменения в API конструктора

Ранее конструктор Driver.js позволял создавать объект без обязательной конфигурации:

const driver = new Driver();

В последних версиях необходимо передавать объект конфигурации, иначе библиотека может вызывать ошибки:

const driver = new Driver({
  animate: true,
  opacity: 0.75,
  padding: 10,
});

Ключевые изменения:

  • Параметр animate теперь по умолчанию true.
  • opacity изменён с 0.5 на 0.75.
  • padding обязателен для корректного позиционирования тултипа.

Изменения в методах управления шагами

defineSteps → defineStep

Ранее метод defineSteps принимал массив объектов шагов:

driver.defineSteps([
  { element: '#btn', popover: { title: 'Кнопка', description: 'Нажмите сюда' } },
  { element: '#menu', popover: { title: 'Меню', description: 'Откройте меню' } },
]);

Теперь метод переименован в defineStep и требует регистрацию каждого шага отдельно:

driver.defineStep({
  element: '#btn',
  popover: { title: 'Кнопка', description: 'Нажмите сюда' }
});

driver.defineStep({
  element: '#menu',
  popover: { title: 'Меню', description: 'Откройте меню' }
});

Это изменение влияет на все проекты, где шаги создавались массивом.

Обновления событий

Ранее использовались события:

  • onNext
  • onPrevious
  • onReset

В новых версиях:

  • Параметры обратных вызовов теперь получают объект eventDetail вместо отдельного элемента.
  • Метод onReset заменён на onStop:
driver.on('next', (eventDetail) => {
  console.log(eventDetail.step);
});

driver.on('stop', () => {
  console.log('Тур завершён');
});

Это изменение ломает обратные вызовы, если использовать старый синтаксис.

Изменения в конфигурации поповера

Позиционирование

  • Старые значения top, bottom, left, right заменены на auto, top-start, top-end и т.д.
  • Значение auto позволяет Driver.js автоматически определять оптимальное положение.

Стилизация

  • Опция className больше не применяется к тултипу напрямую.
  • Необходим новый формат:
popover: {
  title: 'Заголовок',
  description: 'Описание',
  className: 'custom-popover'
}

Работа с элементами DOM

  • Если элемент не найден, библиотека больше не игнорирует его.
  • Теперь выбрасывается исключение ElementNotFoundError.
  • Необходимо проверять наличие элементов до передачи в Driver.js:
const btn = document.querySelector('#btn');
if (btn) {
  driver.defineStep({ element: btn, popover: { title: 'Кнопка' } });
}

Поддержка мобильных устройств

  • Параметр allowClose теперь отключает свайпы по умолчанию.
  • Новые версии не поддерживают фиксированное позиционирование тултипов при скролле на мобильных устройствах.
  • Для корректной работы необходимо включить:
scrollIntoViewOptions: { beh * avior: 'smooth', block: 'center' }

Итоговая проверка перед обновлением

  1. Проверить использование методов defineSteps, onReset и старых событий.
  2. Переписать все шаги, учитывая новый метод defineStep.
  3. Обновить конфигурацию конструктора, поповеров и позиционирования.
  4. Добавить проверки наличия элементов DOM.
  5. Проверить стили и классы, применяемые к тултипу.

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

Оглавление