Координация с позиционированием

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

Пример базовой конфигурации шага:

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

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага',
  attachTo: {
    element: '.button-example',
    on: 'bottom'
  }
});

В поле on можно указать позиции: top, bottom, left, right, а также комбинации вроде top-start, bottom-end. Это позволяет детально контролировать точку привязки подсказки к элементу.

Управление смещением и кастомная точка привязки

Для точной настройки позиции шагов применяется параметр offset, который задаёт смещение подсказки относительно привязанного элемента. Он может быть числом или объектом с координатами по осям x и y:

tour.addStep({
  id: 'offset-step',
  text: 'Шаг со смещением',
  attachTo: {
    element: '.button-example',
    on: 'top'
  },
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: {
          offset: [0, 10] // смещение 10px вниз
        }
      }
    ]
  }
});

Использование popperOptions открывает доступ к полной мощи библиотеки Popper.js, на которой строится позиционирование Shepherd.js. Это позволяет реализовать сложные сценарии: смещение относительно центра, динамическая корректировка при изменении размеров окна и предотвращение выхода подсказки за границы видимой области.

Автоматическое размещение и адаптивность

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

Пример настройки адаптивного шага:

tour.addStep({
  id: 'adaptive-step',
  text: 'Адаптивный шаг',
  attachTo: {
    element: '.menu-item',
    on: 'right'
  },
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: {
          boundary: 'viewport'
        }
      },
      {
        name: 'flip',
        options: {
          fallbackPlacements: ['left', 'bottom', 'top']
        }
      }
    ]
  }
});

Модификатор flip автоматически меняет позицию подсказки на одну из альтернативных, если первоначальное место не помещается. Это обеспечивает корректное отображение на разных разрешениях экрана и при изменении размеров элементов.

Совмещение с прокруткой страницы

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

tour.addStep({
  id: 'scroll-step',
  text: 'Шаг с прокруткой',
  attachTo: {
    element: '.footer-link',
    on: 'top'
  },
  scrollTo: { beh * avior: 'smooth', block: 'center' }
});

Параметры behavior и block управляют анимацией прокрутки и позицией элемента в видимой области, что делает взаимодействие с руководством более естественным.

Использование кастомных контейнеров

По умолчанию Shepherd.js добавляет подсказки в body. Для сложных макетов возможно указание кастомного контейнера, чтобы контролировать наложение элементов, z-index и позиционирование:

tour.addStep({
  id: 'custom-container-step',
  text: 'Шаг в пользовательском контейнере',
  attachTo: {
    element: '.sidebar-button',
    on: 'right'
  },
  useModalOverlay: true,
  modal: true,
  classes: 'custom-tooltip',
  popperOptions: {
    strategy: 'fixed'
  }
});

strategy: 'fixed' позволяет фиксировать подсказку относительно окна, а не относительно документа, что критично для динамически изменяемых панелей и модальных окон.

Динамическое изменение позиции шагов

Позиция шага может быть изменена во время выполнения тура, что удобно для адаптивного интерфейса или интерактивных элементов. Метод updateStepOptions позволяет подставлять новые параметры attachTo:

tour.getCurrentStep().updateStepOptions({
  attachTo: {
    element: '.new-element',
    on: 'left'
  }
});

Это позволяет подстраивать подсказки под изменения DOM без необходимости перезапуска тура.

Работа с комплексными компонентами

Для элементов с динамическим содержимым (списки, таблицы, вкладки) рекомендуется использовать динамический поиск элемента через функцию, возвращающую актуальный DOM-узел:

tour.addStep({
  id: 'dynamic-element-step',
  text: 'Шаг для динамического элемента',
  attachTo: {
    element: () => document.querySelector('.dynamic-button'),
    on: 'bottom'
  }
});

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

Основные рекомендации по позиционированию

  • Всегда проверять видимость целевого элемента перед отображением шага.
  • Использовать flip и preventOverflow для автоматической адаптации на разных разрешениях.
  • Применять offset для тонкой настройки положения и предотвращения перекрытия соседних элементов.
  • При динамическом контенте использовать функции вместо прямых селекторов для attachTo.element.
  • Для модальных окон и фиксированных панелей использовать стратегию fixed и кастомные контейнеры.

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

Оглавление