Базовые позиции размещения

В Shepherd.js позиционирование шагов является ключевым аспектом создания удобного и интуитивного пользовательского руководства. Библиотека использует объект attachTo для привязки шага к определённому элементу DOM и определения позиции относительно него.

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

tour.addStep({
  id: 'example-step',
  text: 'Пример шага',
  attachTo: {
    element: '.my-element',
    on: 'bottom'
  }
});
  • element — селектор DOM-элемента, к которому привязывается шаг. Можно использовать CSS-селекторы или сам DOM-объект.
  • on — позиция шага относительно выбранного элемента: top, bottom, left, right, top-start, top-end, bottom-start, bottom-end и аналогичные. Каждая позиция управляет направлением стрелки и местом отображения подсказки.

Позиционные варианты и их особенности

Простые позиции

  • top — шаг появляется над элементом. Подходит, если область под элементом занята.
  • bottom — шаг появляется под элементом. Чаще всего используется для стандартных тултипов.
  • left — шаг слева от элемента. Удобно, если элемент находится справа.
  • right — шаг справа от элемента. Применяется для боковых панелей или кнопок слева.

Расширенные позиции

  • top-start / top-end — шаг располагается сверху, но выравнивается соответственно по левому или правому краю элемента.
  • bottom-start / bottom-end — шаг располагается снизу, с выравниванием по левому или правому краю.
  • left-start / left-end и right-start / right-end — позволяют дополнительно корректировать положение шага, чтобы избежать перекрытия элементов на странице.

Настройка смещения шагов

Shepherd.js позволяет точно управлять смещением шагов относительно выбранного элемента с помощью свойства offset в объекте attachTo. Оно принимает массив из двух чисел [x, y], где:

  • x — горизонтальное смещение.
  • y — вертикальное смещение.
attachTo: {
  element: '.my-element',
  on: 'bottom',
  offset: [10, 20]
}

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

Автоматическое позиционирование

Если указание позиции невозможно из-за ограничений пространства, Shepherd.js использует автоматическое позиционирование. Для этого можно задать опцию fallback:

attachTo: {
  element: '.my-element',
  on: 'top',
  fallback: ['bottom', 'right', 'left']
}

Библиотека попробует разместить шаг в первой позиции (top), и если элемент не помещается, она последовательно проверит позиции из массива fallback.

Плавная прокрутка к элементу

Опция scrollTo отвечает за автоматическую прокрутку страницы к элементу при активации шага:

defaultStepOptions: {
  scrollTo: { beh * avior: 'smooth', block: 'center' }
}
  • beh * avior: 'smooth' — анимация прокрутки.
  • block: 'center' — выравнивание элемента по центру окна при прокрутке.

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

Особенности адаптивного позиционирования

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

  • Автоматически избегать выхода подсказки за границы окна.
  • Переносить стрелку на противоположную сторону, если место ограничено.
  • Динамически менять смещение для оптимального отображения.
attachTo: {
  element: '.my-element',
  on: 'bottom',
  popperOptions: {
    modifiers: [
      { name: 'offset', options: { offset: [0, 8] } },
      { name: 'preventOverflow', options: { padding: 10 } }
    ]
  }
}

Советы по выбору позиции

  • Использовать bottom по умолчанию, так как это естественная зона восприятия подсказки.
  • Для кнопок и элементов интерфейса, расположенных у края экрана, применять fallback или start/end варианты.
  • При размещении сложных шагов с большим текстом учитывать вертикальные и горизонтальные смещения.
  • Проверять видимость шага на мобильных устройствах, чтобы не закрывать важный контент.

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

Оглавление