State для управления состоянием

Shepherd.js — библиотека для создания интерактивных руководств по интерфейсу. Одним из ключевых аспектов её функциональности является управление состоянием (state), что позволяет контролировать поведение шагов, их видимость, активность кнопок и условия перехода.

Основные концепции состояния

В Shepherd.js состояние каждого шага и всего тура определяется набором ключевых параметров:

  • active — указывает, активен ли шаг в текущий момент.
  • enabled — включает или отключает шаг без удаления его из тура.
  • hidden — скрывает шаг, но оставляет его в последовательности.
  • completed — отмечает шаг как выполненный, что полезно для условной логики перехода между шагами.

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

Инициализация состояния

Состояние шага задаётся при его создании через объект конфигурации:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в тур!',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ],
  when: {
    show: () => console.log('Шаг intro показан')
  },
  enabled: true,
  hidden: false
});

Здесь enabled и hidden управляют доступностью и видимостью шага, а when.show позволяет выполнять действия при активации шага.

Динамическое изменение состояния

Shepherd.js предоставляет методы для управления состоянием после создания шага:

  • step.show() — делает шаг видимым и активным.
  • step.hide() — скрывает шаг.
  • step.enable() / step.disable() — включает или отключает шаг.
  • step.complete() — отмечает шаг как выполненный.
  • step.reset() — сбрасывает состояние шага к исходным параметрам.

Пример динамического управления:

tour.addStep({
  id: 'feature-step',
  text: 'Этот шаг появится только после выполнения предыдущего.',
  buttons: [
    {
      text: 'Далее',
      action: () => {
        step.complete();
        tour.next();
      }
    }
  ],
  enabled: false
});

// Включение шага при выполнении условия
if (userHasCompletedTask) {
  tour.getById('feature-step').enable();
}

Использование состояния для условного показа шагов

Часто необходимо показывать или скрывать шаги на основе действий пользователя. Для этого используют комбинацию свойств enabled, hidden и событий when:

tour.addStep({
  id: 'conditional-step',
  text: 'Этот шаг виден только если выполнено условие',
  hidden: true,
  when: {
    show: () => console.log('Conditional step показан')
  }
});

// Условное отображение
if (userHasAccess) {
  const step = tour.getById('conditional-step');
  step.hidden = false;
  step.show();
}

Состояние тура и глобальные события

Shepherd.js позволяет управлять состоянием не только отдельных шагов, но и всего тура. Тур может находиться в состояниях:

  • active — тур запущен и отображает шаги.
  • complete — тур завершён, все шаги выполнены.
  • canceled — тур был прерван пользователем.

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

tour.on('start', () => console.log('Тур запущен'));
tour.on('complete', () => console.log('Тур завершен'));
tour.on('cancel', () => console.log('Тур отменен'));

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

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

Для адаптивных туров удобно сохранять состояние шагов между сессиями. Shepherd.js позволяет интегрировать внешние хранилища (localStorage, IndexedDB, Redux):

tour.on('complete', () => {
  localStorage.setItem('tourCompleted', 'true');
});

if (localStorage.getItem('tourCompleted') === 'true') {
  tour.getById('intro').disable();
}

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

Комбинирование состояний и действий

Состояние в Shepherd.js тесно связано с действиями, которые выполняются на шаге. Примеры:

  • Блокировка кнопок до выполнения условия:
buttons: [
  {
    text: 'Далее',
    action: tour.next,
    disabled: true
  }
]
  • Автоматический переход после выполнения условия:
when: {
  show: () => {
    if (userCompletedAction) tour.next();
  }
}
  • Динамическая смена текста кнопки:
step.updateStepOptions({
  buttons: [
    {
      text: userHasCompletedAction ? 'Завершить' : 'Пропустить',
      action: tour.next
    }
  ]
});

Эти методы позволяют строить полностью интерактивные, контекстно-зависимые туры.

Вывод

Управление состоянием в Shepherd.js — это сочетание свойств enabled, hidden, completed, методов шагов и глобальных событий тура. Правильное использование этих инструментов позволяет создавать интерактивные, адаптивные и условно-зависимые туры, которые подстраиваются под действия пользователя и сохраняют прогресс между сессиями, обеспечивая гибкость и высокое качество UX.

Оглавление