События и их параметры

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

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

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

Intro.js поддерживает следующие ключевые события:

  1. onbeforechange(targetElement) Срабатывает перед переходом на новый шаг. Параметры:

    • targetElement – DOM-элемент, на который будет сделан переход. Используется для проверки условий или модификации элемента перед его выделением.

  2. onchange(targetElement) Срабатывает сразу после перехода на новый шаг. Параметры:

    • targetElement – DOM-элемент текущего шага. Этот обработчик полезен для динамического изменения содержимого подсказки, добавления кастомных стилей или запуска анимаций.

  3. onafterchange(targetElement) Срабатывает после того, как шаг полностью отобразился. Параметры:

    • targetElement – элемент текущего шага. Позволяет запускать действия, которые должны произойти только после полной визуализации подсказки.

  4. onbeforeexit() Срабатывает перед завершением интро, вне зависимости от того, завершено ли оно пользователем или программно. Возвращаемое значение:

    • true или false – можно вернуть false, чтобы предотвратить завершение интро. Используется для проверки обязательных действий или сохранения данных перед закрытием.

  5. onexit() Срабатывает при окончании интро. Обычно используется для восстановления состояния страницы или запуска логики после завершения руководства.

Дополнительные события для шагов

  • oncomplete() Срабатывает при завершении всех шагов интро. Применяется для уведомления пользователя о полном прохождении руководства и запуска любых финальных действий.

  • onhintclick(element, hint, index) Связано с подсказками (hints) на странице. Параметры:

    • element – DOM-элемент, к которому привязана подсказка.
    • hint – объект подсказки.
    • index – порядковый номер подсказки. Позволяет реагировать на клик по подсказке, например, показывать дополнительную информацию или запускать анимацию.

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

Каждое событие предоставляет контекст текущего шага, который включает следующие ключевые свойства:

  • element – DOM-элемент шага.
  • step – номер текущего шага (начиная с 0).
  • intro – текст подсказки, который будет отображен для шага.
  • position – положение подсказки относительно элемента (top, bottom, left, right, auto).
  • tooltipClass – пользовательский CSS-класс для подсказки.
  • highlightClass – CSS-класс для подсвечивания элемента.

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

Примеры использования

const intro = introJs();

intro.setOptions({
  steps: [
    { element: '#step1', intro: 'Первый шаг', position: 'bottom' },
    { element: '#step2', intro: 'Второй шаг', position: 'right' },
  ]
});

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

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

intro.onafterchange(function(targetElement) {
  console.log('Шаг полностью отобразился:', targetElement.id);
});

intro.onbeforeexit(function() {
  if (!confirm('Вы уверены, что хотите завершить руководство?')) {
    return false; // предотвращает выход
  }
});

intro.onexit(function() {
  console.log('Интро завершено');
});

intro.start();

Управление событиями на лету

Intro.js позволяет добавлять события в процессе выполнения, что делает его гибким для динамических интерфейсов:

intro.onchange(function(targetElement) {
  if (targetElement.id === 'specialStep') {
    targetElement.style.backgroundColor = 'yellow';
  }
});

Можно также использовать вложенные проверки для изменения следующего шага:

intro.onbeforechange(function(targetElement) {
  if (!userHasPermission()) {
    intro.goToStep(3); // перескакиваем на шаг 4
  }
});

Практические рекомендации

  • Использовать onbeforechange для проверок и валидаций.
  • Использовать onchange для изменения внешнего вида элементов на шаге.
  • Использовать onafterchange для запуска анимаций и тяжелых операций, чтобы не блокировать отображение.
  • onbeforeexit — единственное место, где можно предотвратить завершение интро.
  • Всегда проверять наличие targetElement, чтобы избежать ошибок при динамических DOM-структурах.

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

Оглавление