Возвращаемые значения

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

Методы, возвращающие значения

start()

Метод start() инициирует тур и возвращает объект, через который можно отслеживать состояние. Например:

var tour = introJs();
var instance = tour.start();

Возвращаемое значение instance — это объект типа IntroJs, обладающий методами для дальнейшего управления туром, такими как nextStep(), goToStep(), exit().

exit()

Метод exit() завершает текущий тур. Возвращаемое значение отсутствует (undefined), однако событие завершения можно отследить через oncomplete или onexit.

tour.onexit(function() {
    console.log("Тур был прерван пользователем");
});
tour.exit();

goToStep(number)

Позволяет перейти к определенному шагу. Возвращаемое значение — объект IntroJs, что позволяет строить цепочки вызовов:

tour.goToStep(3).start();

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

Объект состояния тура

Объект, возвращаемый start(), содержит внутреннее состояние тура, которое можно использовать для получения информации о текущем шаге:

  • currentStep() — номер текущего шага.
  • currentElement() — DOM-элемент текущего шага.
  • isActive() — флаг, указывающий, активен ли тур.

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

var instance = introJs().start();

console.log("Текущий шаг:", instance.currentStep());
console.log("Активен ли тур?", instance.isActive());

Обработка событий с возвращаемыми данными

Intro.js позволяет подписываться на события, которые возвращают полезные данные:

  • onchange — вызывается при переходе на новый шаг. Аргумент функции — объект с информацией о шаге:
tour.onchange(function(targetElement) {
    console.log("Переход к шагу:", targetElement);
});
  • onbeforechange — позволяет прервать или модифицировать переход. Возвращаемое значение функции может быть false, чтобы остановить движение тура:
tour.onbeforechange(function(targetElement) {
    if (!userAllowed) return false;
});
  • oncomplete — вызывается после успешного завершения тура, возвращает объект тура:
tour.oncomplete(function() {
    console.log("Тур завершен");
});
  • onexit — вызывается при досрочном завершении, возвращает объект с текущим шагом:
tour.onexit(function() {
    console.log("Тур прерван на шаге:", tour.currentStep());
});

Возвращаемые значения при асинхронной логике

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

tour.onbeforechange(async function(targetElement) {
    const allow = await checkUserPermission();
    return allow;
});

Здесь возвращаемое значение функции определяет, разрешён ли переход к следующему шагу.

Цепочка вызовов и fluent-интерфейс

Объект IntroJs, возвращаемый большинством методов, поддерживает fluent-интерфейс, что позволяет строить цепочки:

introJs()
    .setOptions({ showStepNumbers: true })
    .onchange(handleChange)
    .start()
    .nextStep();

Каждый метод возвращает объект IntroJs, что упрощает работу с возвращаемыми значениями и позволяет программно управлять туром без необходимости хранить множество отдельных переменных.

Возвращаемые значения из пользовательских подсказок

Для шагов, где используется custom tooltip, можно получать данные из пользовательских элементов формы:

introJs()
  .setOptions({
    steps: [
      {
        element: '#input-name',
        intro: '<input id="nameField" type="text">'
      }
    ]
  })
  .onafterchange(function(targetElement) {
    const value = document.querySelector('#nameField').value;
    console.log("Введенное значение:", value);
  })
  .start();

Таким образом, возвращаемое значение фактически формируется динамически на основе DOM, что расширяет возможности интеграции туров с приложением.

Практическое использование возвращаемых значений

  1. Отслеживание прогресса: currentStep() позволяет сохранять шаг в базе данных или локальном хранилище.
  2. Условная логика: onbeforechange с возвращаемым false блокирует шаги при несоблюдении условий.
  3. Интеграция с формами: onafterchange предоставляет доступ к введенным пользователем данным.
  4. Флеш-тур и адаптивные шаги: цепочки методов позволяют динамически менять шаги на основе возвращаемых данных.

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

Оглавление