Обработчики событий кнопок

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

Структура кнопок в шаге

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true
  }
});

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага',
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Каждая кнопка представляет собой объект с ключевыми свойствами:

  • text — текст, отображаемый на кнопке.
  • action — функция, вызываемая при клике на кнопку. Можно использовать встроенные методы тура (tour.next(), tour.back(), tour.complete()) или кастомные функции.
  • classes — CSS-классы для стилизации кнопки.
  • secondary — булево значение, указывающее, что кнопка является вторичной (обычно отображается с меньшей визуальной акцентуацией).

Встроенные действия

Shepherd.js поставляется с набором встроенных методов для кнопок:

  • tour.next() — переход к следующему шагу.
  • tour.back() — возврат к предыдущему шагу.
  • tour.cancel() — завершение тура досрочно.
  • tour.complete() — завершение тура после последнего шага.

Эти методы можно использовать напрямую в свойстве action кнопки:

buttons: [
  {
    text: 'Отмена',
    action: tour.cancel,
    classes: 'btn-secondary'
  },
  {
    text: 'Далее',
    action: tour.next,
    classes: 'btn-primary'
  }
]

Кастомные обработчики действий

Кнопки могут выполнять любые функции. Важное отличие — передача функции, а не вызов метода напрямую. Пример с логированием:

buttons: [
  {
    text: 'Лог',
    action: function() {
      console.log('Пользователь нажал кнопку Лог');
      tour.next();
    },
    classes: 'btn-log'
  }
]

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

Использование стрелочных функций и this

Для кнопок можно использовать стрелочные функции, но важно помнить, что стрелочные функции не создают собственного контекста this. В обычной функции this будет ссылаться на сам шаг:

buttons: [
  {
    text: 'Показать id шага',
    action: function() {
      console.log(this.id); // выводит id текущего шага
      tour.next();
    }
  }
]

Если используется стрелочная функция, доступ к this будет внешним, что иногда неудобно для динамических шагов.

Управление видимостью кнопок

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

step.updateStepOptions({
  buttons: [
    {
      text: 'Пропустить',
      action: tour.next,
      classes: 'btn-secondary'
    },
    {
      text: 'Подробно',
      action: function() {
        alert('Показ дополнительной информации');
      },
      classes: 'btn-primary'
    }
  ]
});

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

Обработка событий жизненного цикла шага

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

  • show — когда шаг отображается.
  • hide — когда шаг скрывается.
  • cancel — когда тур отменён.
  • complete — когда тур завершён.

Пример:

tour.addStep({
  id: 'step-with-event',
  text: 'Шаг с обработчиком события',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ],
  when: {
    show: function() {
      console.log('Шаг отображён');
    },
    hide: function() {
      console.log('Шаг скрыт');
    }
  }
});

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

Динамическая генерация кнопок

Кнопки можно генерировать программно в зависимости от состояния приложения:

function generateButtons(userRole) {
  if (userRole === 'admin') {
    return [
      { text: 'Назад', action: tour.back },
      { text: 'Удалить', action: () => alert('Удалено'), classes: 'btn-danger' },
      { text: 'Далее', action: tour.next }
    ];
  } else {
    return [
      { text: 'Назад', action: tour.back },
      { text: 'Далее', action: tour.next }
    ];
  }
}

tour.addStep({
  id: 'dynamic-step',
  text: 'Динамические кнопки',
  buttons: generateButtons(currentUser.role)
});

Такой подход делает интерфейс тура адаптивным под роль пользователя или состояние приложения.

Важные рекомендации по работе с кнопками

  1. Не смешивать вызовы метода и ссылку на функцию:

    • Правильно: action: tour.next
    • Неправильно: action: tour.next() (вызовет сразу при создании кнопки).

  2. Использовать CSS-классы для визуального разделения кнопок: вторичные действия (secondary) и основные (primary).

  3. Обеспечивать последовательность действий: для сложной логики рекомендуется комбинировать кастомные функции и встроенные методы тура.

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

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

Оглавление