Изменения в API между версиями

Библиотека Intro.js предназначена для создания пошаговых интерактивных руководств по интерфейсу веб-приложений. С течением времени её API претерпело несколько важных изменений, которые необходимо учитывать при обновлении проектов или при изучении последних версий.

Инициализация и конфигурация

Ранее, до версии 5.x, стандартный способ запуска интро выглядел так:

introJs().setOptions({
  steps: [
    { element: '#step1', intro: 'Первый шаг' },
    { element: '#step2', intro: 'Второй шаг' }
  ],
  showStepNumbers: true,
  exitOnOverlayClick: false
}).start();

В версии 6.x и выше появились следующие ключевые изменения:

  • Метод setOptions теперь может принимать ES6 объект конфигурации с поддержкой дополнительных опций, таких как disableInteraction, tooltipClass, scrollToElement.
  • Прямой вызов start() без предварительной инициализации объекта Intro.js возможен, но рекомендуется создавать отдельную переменную для повторного использования:
const intro = introJs();
intro.setOptions({
  steps: [
    { element: '#step1', intro: 'Первый шаг', position: 'bottom' },
    { element: '#step2', intro: 'Второй шаг', position: 'top' }
  ],
  disableInteraction: true
});
intro.start();
  • Параметр showStepNumbers заменён на showStepNumbers: true/false с поддержкой кастомизации через CSS-класс stepNumberClass.

Работа со шагами

Изменения структуры шагов:

  1. position – раньше допускалось использовать строковые значения вроде "auto", "top", "left"; в новых версиях можно указывать массив предпочтительных позиций, что позволяет библиотеке автоматически выбирать оптимальное размещение тултипа:
steps: [
  { element: '#step1', intro: 'Описание', position: ['top', 'right', 'bottom'] }
]
  1. title – введён новый ключ для заголовка шага, который отделён от текста описания. Пример:
{ element: '#step1', title: 'Заголовок шага', intro: 'Описание шага' }
  1. tooltipClass – возможность назначать уникальный CSS-класс для тултипа на каждом шаге, что позволяет индивидуально стилизовать отдельные шаги.

События

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

  • onbeforechange(function(targetElement) {}) – вызывается перед переходом на шаг.
  • onchange(function(targetElement) {}) – вызывается при изменении шага.
  • onafterchange(function(targetElement) {}) – новый метод, вызывается после рендеринга тултипа, что позволяет безопасно модифицировать DOM внутри шага.
  • oncomplete(function() {}) – завершение интро, осталось без изменений.
  • onexit(function() {}) – добавлено, заменяет устаревший onexit с другим поведением, особенно при закрытии через клавишу ESC или клик по оверлею.

Пример регистрации событий:

intro.onbeforechange(function(targetElement) {
  console.log('Переход к шагу с элементом:', targetElement.id);
});

intro.onafterchange(function(targetElement) {
  targetElement.style.border = '2px solid red';
});

intro.oncomplete(function() {
  console.log('Интерактивное руководство завершено');
});

Настройки поведения и интерактивности

  1. disableInteraction – заменяет прежние exitOnOverlayClick и exitOnEsc для большей гибкости. Позволяет заблокировать любые действия пользователя на фоне и элементах, кроме кнопок управления Intro.js.

  2. scrollToElement – новый параметр, управляет автопрокруткой к текущему шагу. Возможные значения: true (по умолчанию), false, или функция кастомного скролла.

  3. keyboardNavigation – включение или отключение навигации с клавиатуры, раньше клавиатура работала всегда.

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

В последних версиях изменилось поведение тултипов на мобильных устройствах:

  • Автоматический ресайз тултипа для маленьких экранов.
  • Возможность указать отдельные позиции шага для мобильных и десктопных устройств через position как массив объектов:
steps: [
  {
    element: '#step1',
    intro: 'Описание',
    position: [
      { device: 'desktop', value: 'right' },
      { device: 'mobile', value: 'bottom' }
    ]
  }
]

Работа с кастомными кнопками

С версии 6.x появилась поддержка кастомных кнопок навигации. Старый подход через nextLabel, prevLabel остался, но расширен за счёт:

  • skipLabel – текст кнопки пропуска.
  • doneLabel – текст завершения.
  • Возможность скрывать или динамически изменять кнопки через CSS или JS.

Пример:

intro.setOptions({
  steps: [
    { element: '#step1', intro: 'Первый шаг', position: 'top' }
  ],
  nextLabel: 'Вперед',
  prevLabel: 'Назад',
  skipLabel: 'Пропустить',
  doneLabel: 'Готово'
});

Примечания по миграции с версии 5.x на 6.x

  • Все методы цепочки (.setOptions(), .start()) остались совместимыми, но для полного контроля рекомендуется создавать отдельный объект Intro.js.
  • Старые ключи exitOnOverlayClick и exitOnEsc следует заменить на disableInteraction с корректными значениями.
  • Событие onchange теперь не гарантирует момент окончания анимации тултипа; для работы после рендера необходимо использовать onafterchange.
  • Новые возможности позиционирования позволяют создавать более гибкие и адаптивные интерфейсы, особенно для мобильных пользователей.

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

Оглавление