Опции scrollToHandler

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

Тип значения scrollToHandler

Опция scrollToHandler принимает функцию, которая вызывается каждый раз, когда Shepherd пытается прокрутить страницу к целевому элементу шага:

scrollToHandler: function (targetElement) {
  // Логика прокрутки
}
  • targetElement — DOM-элемент, к которому привязан текущий шаг тура.
  • Функция может использовать любой метод прокрутки, включая стандартные scrollIntoView, window.scrollTo или сторонние анимации через библиотеки типа GSAP.

Поведение по умолчанию

Если scrollToHandler не задан, Shepherd.js применяет встроенный метод прокрутки:

  • Используется scrollIntoView({ beh * avior: 'smooth', block: 'center' }).
  • Элемент центрируется по вертикали относительно видимой области.
  • Для фиксированных элементов шапки или футера может потребоваться дополнительная настройка, иначе элемент будет частично перекрыт.

Примеры кастомной прокрутки

1. Смещение с учётом фиксированной шапки

scrollToHandler: function (targetElement) {
  const headerOffset = 100; // Высота шапки
  const elementPosition = targetElement.getBoundingClientRect().top;
  const offsetPosition = elementPosition + window.pageYOffset - headerOffset;

  window.scrollTo({
    top: offsetPosition,
    beh * avior: "smooth"
  });
}

В этом примере элемент прокручивается так, чтобы его верхняя граница находилась под шапкой.

2. Анимация с использованием сторонней библиотеки

scrollToHandler: function (targetElement) {
  gsap.to(window, { duration: 1, scrollTo: targetElement });
}

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

3. Прокрутка только при необходимости

scrollToHandler: function (targetElement) {
  const rect = targetElement.getBoundingClientRect();
  if (rect.top < 0 || rect.bottom > window.innerHeight) {
    targetElement.scrollIntoView({ beh * avior: "smooth", block: "center" });
  }
}

Функция проверяет видимость элемента и прокручивает страницу только если элемент частично или полностью вне видимой области.

Контроль прокрутки для динамического контента

При использовании динамических компонентов (например, вкладок, модальных окон, ленивой загрузки контента) часто требуется:

  • Добавить задержку перед прокруткой, чтобы элемент успел появиться в DOM.
  • Использовать промисы или события загрузки контента.
scrollToHandler: async function (targetElement) {
  await new Promise(resolve => setTimeout(resolve, 300)); // Ждем рендер
  targetElement.scrollIntoView({ beh * avior: "smooth", block: "center" });
}

Это предотвращает ситуации, когда Shepherd прокручивает к элементу, который ещё не отрендерен на странице.

Советы по использованию

  • scrollToHandler может использоваться для совместимости с любыми кастомными скроллерами, включая виртуальные списки и контейнеры с overflow.
  • Для сложных интерфейсов рекомендуется всегда проверять видимость элемента перед прокруткой, чтобы избежать непредсказуемого поведения.
  • Можно комбинировать scrollToHandler с опциями attachTo и advanceOn для синхронизации показа шага с событиями интерфейса.

Отличие от scrollTo

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

Итоговые ключевые моменты

  • scrollToHandler — это функция для кастомного управления прокруткой к целевому элементу шага.
  • Позволяет учитывать фиксированные элементы, динамический контент и сложные UI-структуры.
  • Поддерживает любые методы прокрутки, включая сторонние библиотеки и анимации.
  • Рекомендуется всегда проверять видимость элемента и учитывать задержку при динамической подгрузке контента.
Оглавление