Миграция со старых версий

При обновлении библиотеки Intro.js с версий 1.x или 2.x на более современные релизы (3.x и выше) важно учитывать изменения в API, структуре конфигурации и поведении методов. Несоблюдение этих изменений может привести к некорректной работе подсказок и неправильной инициализации шагов.

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

  1. Инициализация и создание экземпляра

В старых версиях часто использовался прямой вызов introJs().start();. В новых версиях рекомендуется создавать отдельный экземпляр с последующей конфигурацией:

const intro = introJs();
intro.setOptions({
  steps: [
    { 
      element: '#step1', 
      intro: 'Это первый шаг' 
    },
    { 
      element: '#step2', 
      intro: 'Это второй шаг' 
    }
  ],
  showProgress: true
});
intro.start();

Ключевое отличие: теперь setOptions принимает объект конфигурации, который может включать массив шагов, глобальные настройки и параметры навигации.

  1. Конфигурационные изменения

  • tooltipPosition → position Старый параметр tooltipPosition заменён на position. Возможные значения остались прежними: top, bottom, left, right, auto.

  • hidePrev и hideNext Для контроля видимости кнопок теперь используются методы экземпляра:

    intro.setOption('showButtons', true); // Показывать все кнопки
intro.setOption('hidePrev', false);   // Не скрывать кнопку "Назад"

  • nextLabel и prevLabel Настройка текста кнопок теперь через объект опций:

    intro.setOptions({
  nextLabel: 'Вперёд',
  prevLabel: 'Назад',
  skipLabel: 'Пропустить',
  doneLabel: 'Готово'
});

Шаги и их структура

Ранее шаги определялись в виде простого массива объектов с полями element и intro. В современных версиях добавлены расширенные возможности:

  • position — явное указание позиции тултипа.
  • tooltipClass — кастомизация класса для тултипа.
  • highlightClass — класс для подсветки элемента.
  • disableInteraction — блокировка взаимодействия с элементом во время шага.

Пример:

intro.setOptions({
  steps: [
    {
      element: '#feature1',
      intro: 'Описание функции 1',
      position: 'right',
      tooltipClass: 'custom-tooltip',
      highlightClass: 'highlighted-element',
      disableInteraction: true
    },
    {
      element: '#feature2',
      intro: 'Описание функции 2',
      position: 'bottom'
    }
  ]
});

События и обработчики

В старых версиях активно использовались onbeforechange, onchange, oncomplete, onexit. В новых релизах синтаксис слегка изменился:

intro.onbeforechange(function(targetElement) {
  console.log('Перед сменой шага:', targetElement);
});

intro.onchange(function(targetElement) {
  console.log('Шаг изменён на элемент:', targetElement);
});

intro.oncomplete(function() {
  console.log('Тур завершён');
});

intro.onexit(function() {
  console.log('Тур прерван пользователем');
});

Особенности:

  • События теперь работают исключительно на экземпляре, а не глобально.
  • Методы можно цепочить для более чистой записи:
intro
  .onchange(elem => console.log('Шаг:', elem))
  .oncomplete(() => console.log('Готово'))
  .start();

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

В старых версиях динамически добавленные DOM-элементы часто не отображались корректно, так как шаги формировались при первом вызове start(). В новых версиях для динамических шагов рекомендуется использовать refresh() перед переходом на шаг:

// Добавили новый элемент в DOM
document.body.insertAdjacentHTML('beforeend', '<div id="newStep">Новый шаг</div>');

intro.setOptions({
  steps: [
    { element: '#existingStep', intro: 'Старый шаг' },
    { element: '#newStep', intro: 'Новый динамический шаг' }
  ]
});

intro.refresh(); // Обновление позиции и состояния шагов
intro.start();

Локализация и кастомные тексты

Ранее текст кнопок локализовывался через глобальные свойства. Сейчас рекомендуется задавать локализацию напрямую через setOptions для конкретного экземпляра:

intro.setOptions({
  nextLabel: 'Далее',
  prevLabel: 'Назад',
  skipLabel: 'Пропустить',
  doneLabel: 'Завершить'
});

Дополнительно можно менять классы тултипов для кастомной стилизации текста:

intro.setOptions({
  tooltipClass: 'my-tooltip-class'
});

Обновление CSS

С выходом версии 3.x произошли изменения в структуре CSS:

  • Классы introjs-tooltip и introjs-helperLayer сохраняются, но их внутренние элементы (introjs-arrow, introjs-tooltiptext) могут иметь другую вложенность.
  • Настройка внешнего вида через кастомные классы (tooltipClass, highlightClass) теперь более надёжна, чем прямое переопределение глобальных селекторов.

Миграция шагов с нестандартной логикой

Если в старой версии использовались кастомные функции навигации, например:

intro.onbeforechange(function(targetElement) {
  if (targetElement.id === 'step2') {
    intro.nextStep();
  }
});

В новых версиях лучше использовать метод goToStep на экземпляре:

intro.onbeforechange(function(targetElement) {
  if (targetElement.id === 'step2') {
    intro.goToStep(3); // Переход на конкретный шаг
  }
});

Совместимость с фреймворками

Intro.js активно используется с React, Vue и Angular. В новых версиях рекомендуется:

  • Создавать экземпляр при монтировании компонента (componentDidMount в React, mounted в Vue).
  • Использовать refresh() при изменении DOM, особенно для динамических компонентов.
  • Удалять экземпляр при размонтировании для предотвращения утечек памяти.

Если необходимо, могу подготовить подробную таблицу сравнения старых и новых опций Intro.js с конкретными примерами кода для каждой версии, чтобы процесс миграции был максимально наглядным.

Хотите, чтобы я её составил?

Оглавление