Проверка состояния тура

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

Для начала, тур создаётся следующим образом:

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

Здесь steps определяет последовательность элементов и подсказок, которые будут показаны. Важно, что объект тура хранит внутреннее состояние: текущий шаг, завершён ли тур и был ли он ранее показан.

Проверка текущего шага

Метод currentStep() позволяет определить, на каком шаге находится пользователь в данный момент:

const current = tour.currentStep();
console.log('Текущий шаг:', current);
  • Возвращаемое значение — индекс текущего шага (начиная с 0).
  • Если тур не запущен, метод возвращает 0, что соответствует первому шагу.

Проверка завершённости тура

Библиотека предоставляет флаг introJs()._completed для внутреннего отслеживания состояния. Прямое использование не рекомендуется, но его можно применять для отладки:

if (tour._completed) {
    console.log('Тур уже завершён');
} else {
    console.log('Тур ещё не завершён');
}

Более безопасный способ — хранить собственный флаг завершения с использованием событий oncomplete и onexit:

let tourCompleted = false;

tour.oncomplete(() => {
    tourCompleted = true;
});

tour.onexit(() => {
    tourCompleted = true;
});

После этого можно проверять состояние через переменную tourCompleted.

Определение, был ли тур ранее показан

Для длительного хранения состояния между сессиями используют локальное хранилище:

if (localStorage.getItem('introTourCompleted')) {
    console.log('Тур уже был пройден ранее');
} else {
    tour.start();
}

tour.oncomplete(() => {
    localStorage.setItem('introTourCompleted', 'true');
});

tour.onexit(() => {
    localStorage.setItem('introTourCompleted', 'true');
});
  • Такой подход позволяет при перезагрузке страницы определить, показывать тур повторно или нет.
  • Важно использовать как oncomplete, так и onexit, чтобы фиксировать факт прекращения тура пользователем досрочно.

Возобновление тура с конкретного шага

Если требуется продолжить тур с того шага, на котором пользователь остановился, можно использовать метод goToStep(step):

const savedStep = parseInt(localStorage.getItem('introTourStep') || '0', 10);
tour.goToStep(savedStep).start();

tour.onchange((targetElement) => {
    const stepIndex = tour.currentStep();
    localStorage.setItem('introTourStep', stepIndex);
});
  • onchange срабатывает при переходе между шагами.
  • Сохраняется индекс текущего шага, что позволяет при следующем открытии сайта продолжить с этого места.

События для отслеживания состояния тура

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

  • onbeforechange — вызывается до отображения следующего шага, полезно для проверки условий.
  • onchange — срабатывает при каждом шаге, можно сохранять прогресс.
  • oncomplete — вызывается, когда пользователь дошёл до последнего шага.
  • onexit — вызывается, когда тур завершён досрочно.

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

tour.onbeforechange((targetElement) => {
    console.log('Перед изменением шага:', tour.currentStep());
});

tour.onchange((targetElement) => {
    console.log('Сейчас на шаге:', tour.currentStep());
});

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

tour.onexit(() => {
    console.log('Тур досрочно завершён');
});

Использование пользовательских флагов состояния

Помимо локального хранилища, удобно использовать объекты состояния в приложении:

const appState = {
    tourCompleted: false,
    currentTourStep: 0
};

tour.onchange(() => {
    appState.currentTourStep = tour.currentStep();
});

tour.onexit(() => {
    appState.tourCompleted = true;
});

Такой подход особенно полезен при SPA (Single Page Application), где управление состоянием тура может быть интегрировано с глобальным состоянием приложения (например, Redux или Vuex).

Особенности проверки состояния при динамических элементах

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

if (document.querySelector('#dynamicStep')) {
    tour.start();
} else {
    console.log('Элемент для шага не найден, тур не запускается');
}

Это предотвращает ошибки и некорректное отображение подсказок.

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

  • Использовать onchange и currentStep() для точного отслеживания прогресса.
  • Для сохранения состояния между сессиями применять localStorage или куки.
  • Разделять флаги завершения тура (completed) и текущего шага (currentStep) для гибкого управления.
  • Проверять существование элементов перед запуском каждого шага, чтобы тур оставался стабильным даже при изменении DOM.

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

Оглавление