Директивы для шагов

Каждый шаг в Shepherd.js представляет собой конфигурационный объект, описывающий поведение, внешний вид и взаимодействие с пользователем. Директивы — это свойства этого объекта, которые управляют логикой шага: от привязки к DOM-элементу до обработки событий и переходов.

Базовый пример шага:

tour.addStep({
  id: 'example-step',
  text: 'Описание шага',
  attachTo: {
    element: '.button',
    on: 'bottom'
  }
});

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

Директива id

Уникальный идентификатор шага в рамках тура.

Назначение:

  • Позволяет обращаться к шагу программно
  • Используется для навигации (show, hide, cancel)
id: 'welcome-step'

Директива text

Определяет содержимое шага. Может быть строкой, HTML или функцией.

text: 'Нажмите сюда, чтобы продолжить'

Функциональный вариант:

text: () => {
  return 'Динамический текст';
}

Позволяет формировать контент на основе состояния приложения.

Директива attachTo

Связывает шаг с элементом DOM.

attachTo: {
  element: '.nav-item',
  on: 'right'
}

Параметры:

  • element: CSS-селектор или DOM-элемент
  • on: позиция тултипа относительно элемента

Допустимые значения on:

  • top
  • bottom
  • left
  • right
  • auto

Если element не найден, шаг может не отображаться или вести себя некорректно.

Директива buttons

Определяет кнопки внутри шага.

buttons: [
  {
    text: 'Назад',
    action: function() {
      return this.back();
    }
  },
  {
    text: 'Далее',
    action: function() {
      return this.next();
    }
  }
]

Свойства кнопки:

  • text: текст кнопки
  • action: функция при нажатии
  • classes: дополнительные CSS-классы
  • secondary: логическое значение для второстепенных кнопок

Директива advanceOn

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

advanceOn: {
  selector: '.submit-btn',
  event: 'click'
}

Особенности:

  • Удобно для обучения интерфейсу
  • Устраняет необходимость в кнопке “Далее”

Директива when

Определяет обработчики событий жизненного цикла шага.

when: {
  show: () => console.log('Шаг показан'),
  hide: () => console.log('Шаг скрыт')
}

Поддерживаемые события:

  • show
  • hide
  • cancel
  • complete

Используется для интеграции с бизнес-логикой приложения.

Директива beforeShowPromise

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

beforeShowPromise: function() {
  return new Promise(resolve => {
    setTimeout(resolve, 500);
  });
}

Шаг будет показан только после выполнения промиса.

Директива scrollTo

Управляет прокруткой к элементу перед показом шага.

scrollTo: true

Или более гибко:

scrollTo: {
  beh * avior: 'smooth',
  block: 'center'
}

Директива cancelIcon

Добавляет иконку закрытия шага.

cancelIcon: {
  enabled: true
}

Можно расширить:

cancelIcon: {
  enabled: true,
  label: 'Закрыть'
}

Директива classes

Позволяет добавлять кастомные CSS-классы.

classes: 'custom-tooltip dark-theme'

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

Директива highlightClass

Добавляет CSS-класс к целевому элементу.

highlightClass: 'highlighted-element'

Полезно для визуального выделения.

Директива canClickTarget

Определяет, можно ли взаимодействовать с элементом под шагом.

canClickTarget: false

Если false, элемент блокируется overlay-слоем.

Директива modalOverlayOpeningPadding

Настраивает отступ вокруг выделяемого элемента.

modalOverlayOpeningPadding: 10

Директива modalOverlayOpeningRadius

Задает радиус скругления области выделения.

modalOverlayOpeningRadius: 8

Директива arrow

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

arrow: true

Можно отключить:

arrow: false

Директива floatingUIOptions

Позволяет тонко настраивать позиционирование (через Floating UI).

floatingUIOptions: {
  middleware: [
    {
      name: 'offset',
      options: {
        mainAxis: 10
      }
    }
  ]
}

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

Директива showOn

Позволяет условно отображать шаг.

showOn: function() {
  return window.innerWidth > 768;
}

Если функция возвращает false, шаг пропускается.

Директива id и управление шагами

Связка id с методами тура:

tour.show('example-step');

Позволяет переходить к конкретному шагу напрямую.

Комплексный пример шага с директивами

tour.addStep({
  id: 'complex-step',
  text: () => 'Динамическое содержимое',
  attachTo: {
    element: '.profile-button',
    on: 'left'
  },
  classes: 'custom-step',
  highlightClass: 'highlight',
  scrollTo: {
    beh * avior: 'smooth',
    block: 'center'
  },
  cancelIcon: {
    enabled: true
  },
  buttons: [
    {
      text: 'Назад',
      action() {
        return this.back();
      },
      secondary: true
    },
    {
      text: 'Далее',
      action() {
        return this.next();
      }
    }
  ],
  advanceOn: {
    selector: '.profile-button',
    event: 'click'
  },
  when: {
    show() {
      console.log('Показ шага');
    }
  },
  beforeShowPromise() {
    return new Promise(resolve => setTimeout(resolve, 300));
  },
  canClickTarget: true
});

Практические замечания

  • Избыточное количество директив усложняет поддержку, поэтому важно использовать только необходимые
  • Асинхронные директивы (beforeShowPromise) критичны при работе с динамическим DOM
  • advanceOn и buttons не следует смешивать без необходимости — это приводит к дублирующему управлению
  • showOn полезен для адаптивных интерфейсов
  • Использование floatingUIOptions требует понимания механизма позиционирования

Взаимодействие директив между собой

Некоторые директивы влияют друг на друга:

  • attachTo + scrollTo — гарантируют видимость элемента
  • highlightClass + modalOverlayOpeningPadding — формируют визуальный фокус
  • advanceOn может полностью заменить кнопки
  • beforeShowPromise может задержать when.show

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

Оглавление