Получение шага по id

Shepherd.js — это библиотека для создания пошаговых интерактивных туров по веб-приложениям. В основе работы Shepherd лежит объект Tour, который управляет последовательностью шагов (Step). Каждый шаг можно идентифицировать уникальным id, что позволяет получать и модифицировать конкретный шаг после его добавления в тур.

Структура шага и id

Каждый шаг создается с использованием метода addStep объекта Tour. Простейший пример шага с id выглядит так:

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

tour.addStep({
  id: 'intro-step',
  text: 'Это первый шаг тура',
  attachTo: { element: '.header', on: 'bottom' }
});

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

Получение шага по id

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

const step = tour.getById('intro-step');
console.log(step.text); // Выведет: 'Это первый шаг тура'

Метод getById возвращает объект шага (Step) или undefined, если шаг с указанным id не найден.

Работа с объектом шага

После получения шага по id становится доступным полный API шага. Можно:

  • Изменять текст и заголовок:
step.updateStepOptions({
  text: 'Обновленный текст шага'
});
  • Показывать или скрывать шаг вручную:
step.show();
step.hide();
  • Программно переходить к следующему или предыдущему шагу:
step.next();
step.back();
  • Подписываться на события шага:
step.on('show', () => {
  console.log('Шаг показан');
});

Использование id для управления туром

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

  1. Обновление конкретного шага после рендеринга элемента
const step = tour.getById('settings-step');
if (step) {
  step.updateStepOptions({
    attachTo: { element: '.settings-button', on: 'right' }
  });
}
  1. Программное пропускание шага
const step = tour.getById('promo-step');
if (step) {
  step.hide();
  step.next();
}
  1. Добавление кастомного поведения
const step = tour.getById('help-step');
if (step) {
  step.on('hide', () => {
    console.log('Пользователь закрыл подсказку помощи');
  });
}

Важные рекомендации

  • id должен быть строкой и уникальным внутри одного тура. Дублирование id приведет к непредсказуемому поведению при вызове getById.
  • Метод getById безопасен: если шаг не найден, возвращается undefined. Необходимо проверять результат перед вызовом методов шага.
  • Любые изменения через updateStepOptions применяются к существующему шагу мгновенно, включая параметры позиционирования, текст и CSS-классы.

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

tour.addStep({
  id: 'final-step',
  text: 'Финальный шаг',
  attachTo: { element: '.footer', on: 'top' },
  buttons: [
    {
      text: 'Закрыть',
      action: function() {
        tour.cancel();
      }
    }
  ]
});

// Изменение кнопок шага по id
const finalStep = tour.getById('final-step');
if (finalStep) {
  finalStep.updateStepOptions({
    buttons: [
      {
        text: 'Готово',
        action: function() {
          tour.complete();
        }
      }
    ]
  });
}

Использование id для доступа к шагам обеспечивает гибкость при динамическом управлении турами, позволяет модифицировать отдельные шаги без перестроения всего тура и обеспечивает чистый, читаемый код.

Оглавление