advanceOn

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

Синтаксис и базовое использование

tour.addStep({
  id: 'example-step',
  text: 'Нажмите кнопку, чтобы перейти к следующему шагу.',
  attachTo: { element: '#next-button', on: 'bottom' },
  advanceOn: { selector: '#next-button', event: 'click' }
});

В этом примере:

selector — CSS-селектор элемента, событие на котором запускает переход.
event — название DOM-события, при котором активируется переход (например, click, mouseover, input).

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

Продвинутые возможности

Множественные события Можно отслеживать несколько событий с помощью массива:

advanceOn: [
  { selector: '#next', event: 'click' },
  { selector: '#shortcut', event: 'keydown' }
]

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

Кастомные события События не обязательно должны быть встроенными DOM-событиями. Можно использовать пользовательские события через dispatchEvent:

const step = tour.addStep({
  id: 'custom-step',
  text: 'Слушаем кастомное событие',
  advanceOn: { selector: 'body', event: 'myCustomEvent' }
});

// Позже где-то в коде
document.body.dispatchEvent(new Event('myCustomEvent'));

Условное продвижение В новых версиях Shepherd.js можно передавать функцию для проверки условия перед продвижением:

advanceOn: {
  selector: '#input-field',
  event: 'input',
  preventDefault: true,
  callback: (event) => event.target.value.length > 3
}

Здесь шаг перейдёт только если длина введённого текста больше 3 символов. Опция preventDefault позволяет при необходимости остановить стандартное действие события.

Взаимодействие с другими опциями шагов

buttons: кнопки шага и advanceOn могут работать параллельно. advanceOn не блокирует кнопку, но позволяет сделать шаг автоматически без клика.
when: события, заданные через advanceOn, могут запускать хук when (show, hide), обеспечивая синхронизацию пользовательских действий и логики тура.
canClickTarget: важно учитывать, что автоматическое продвижение через advanceOn требует, чтобы элемент был доступен для клика, иначе шаг не сработает.

Типичные ошибки при использовании

Элемент ещё не создан в DOM Если селектор не существует на момент инициализации шага, advanceOn не сработает. Решение: использовать attachTo с асинхронной проверкой наличия элемента или инициализировать шаг после рендера DOM.
Несовпадение события Частая ошибка — использовать событие, которое не поддерживается элементом (например, change на <div>). Следует проверять совместимость событий с элементами.
Перекрытие событий Если на элементе есть несколько слушателей одного события, важно убедиться, что порядок обработки не мешает работе Shepherd.js.

Практические примеры

Автоматическое продвижение после таймера

tour.addStep({
  id: 'auto-step',
  text: 'Шаг автоматически перейдёт через 3 секунды',
  advanceOn: {
    selector: 'body',
    event: 'timeout'
  }
});

// Через 3 секунды:
setTimeout(() => {
  document.body.dispatchEvent(new Event('timeout'));
}, 3000);

Продвижение после изменения поля формы

tour.addStep({
  id: 'input-step',
  text: 'Введите имя для продолжения',
  attachTo: { element: '#name', on: 'right' },
  advanceOn: {
    selector: '#name',
    event: 'input',
    callback: e => e.target.value.trim() !== ''
  }
});