Обновление с версии 1.x

Основные изменения в API

С версии 2.x библиотека Driver.js получила существенные изменения в синтаксисе и структуре конфигурации. Ранее шаги пользовательского тура задавались через массив объектов steps с минимальным набором параметров, таких как element и popover. В новой версии структура стала более гибкой, с поддержкой расширенных опций:

const driver = new Driver({
  animate: true,
  opacity: 0.7,
  padding: 10,
  allowClose: false,
  doneBtnText: 'Завершить',
  closeBtnText: 'Закрыть',
});

Каждый шаг теперь включает:

  • element – CSS-селектор целевого элемента или DOM-узел.

  • popover – объект с настройками всплывающей подсказки:

    • title – заголовок подсказки.
    • description – текстовое содержание.
    • position – расположение относительно элемента (top, bottom, left, right, auto).
    • align – уточняющее выравнивание (start, center, end).
driver.defineSteps([
  {
    element: '#menu',
    popover: {
      title: 'Меню',
      description: 'Здесь отображаются все разделы приложения',
      position: 'right',
    }
  },
  {
    element: '#profile',
    popover: {
      title: 'Профиль',
      description: 'Настройки аккаунта пользователя',
      position: 'left',
    }
  }
]);

Новые возможности навигации

В версии 2.x добавлены новые методы управления шагами:

  • moveNext() – переход к следующему шагу.
  • movePrevious() – возврат к предыдущему шагу.
  • start() – запуск тура с первого шага.
  • reset() – сброс состояния тура.

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

driver.start();
driver.moveNext();
driver.reset();

Кастомизация подсказок

Driver.js 2.x расширил возможности стилизации:

  • className – добавление кастомного класса для popover.
  • closeBtnText и doneBtnText – изменение текста кнопок закрытия и завершения.
  • nextBtnText и prevBtnText – настройка текста кнопок навигации.
  • stageBackground – цвет затемнённого фона вокруг элемента.
  • allowClose – возможность закрыть тур кликом по затемнённой области.
const driver = new Driver({
  stageBackground: 'rgba(0, 0, 0, 0.8)',
  nextBtnText: 'Далее',
  prevBtnText: 'Назад',
  doneBtnText: 'Готово',
  allowClose: true,
});

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

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

  • driver.on('start', callback) – срабатывает при запуске тура.
  • driver.on('next', callback) – перед переходом на следующий шаг.
  • driver.on('previous', callback) – перед возвратом на предыдущий шаг.
  • driver.on('close', callback) – при закрытии тура.
  • driver.on('complete', callback) – при завершении всех шагов.
driver.on('start', () => console.log('Тур запущен'));
driver.on('complete', () => console.log('Тур завершён'));

Работа с динамическими элементами

Теперь Driver.js поддерживает динамически создаваемые элементы. Для этого в настройках шага можно использовать element как функцию, возвращающую текущий DOM-узел. Это удобно при работе с SPA и динамическими компонентами.

driver.defineSteps([
  {
    element: () => document.querySelector('#dynamic-element'),
    popover: {
      title: 'Динамический элемент',
      description: 'Элемент создаётся после загрузки страницы',
      position: 'bottom',
    }
  }
]);

Совместимость и миграция

Для миграции с версии 1.x на 2.x необходимо:

  1. Переписать конфигурацию шагов в формат driver.defineSteps().
  2. Проверить использование popover.position, так как некоторые позиции изменили поведение при авто-вирации.
  3. Пересмотреть кастомные события и обработчики, так как onNext, onPrevious заменены на глобальные события next, previous.
  4. Адаптировать стили подсказок под новые свойства className и stageBackground.

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

Особенности производительности

  • Оптимизирован рендер затемнённого фона, минимизировано влияние на DOM.
  • Lazy-инициализация popover позволяет ускорить загрузку страниц с большим количеством элементов.
  • Асинхронная обработка шагов снижает вероятность конфликта с библиотеками SPA, такими как React или Vue.

Примеры сложных сценариев

  1. Тур с условной логикой:
driver.defineSteps([
  {
    element: '#step1',
    popover: { title: 'Шаг 1', description: 'Описание шага 1', position: 'top' },
    onNext: () => {
      if (!user.hasCompletedStep1) driver.skipStep();
    }
  },
  {
    element: '#step2',
    popover: { title: 'Шаг 2', description: 'Описание шага 2', position: 'right' }
  }
]);
  1. Тур с несколькими турами на одной странице:
const driverA = new Driver({ opacity: 0.6 });
const driverB = new Driver({ opacity: 0.8 });

driverA.defineSteps([...]);
driverB.defineSteps([...]);

driverA.start();
// По завершении driverA
driverB.start();
  1. Интеграция с SPA: использование функций для element, событий start и complete для динамического построения и удаления подсказок при переходах между страницами.

В результате переход на Driver.js 2.x обеспечивает современный, масштабируемый подход к созданию интерактивных туров с полным контролем над поведением, стилями и навигацией.

Оглавление