attachTo

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

Синтаксис

attachTo: {
  element: String | HTMLElement,
  on: String
}

  • element — CSS-селектор или объект HTMLElement, к которому привязывается шаг.

  • on — сторона, относительно которой будет отображаться подсказка. Возможные значения:

    • 'top' — выше элемента
    • 'bottom' — ниже элемента
    • 'left' — слева
    • 'right' — справа
    • 'auto' — библиотека автоматически подбирает оптимальное положение

Примеры использования

Привязка к элементу по селектору:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
  }
});

tour.addStep({
  id: 'step-1',
  text: 'Это первый шаг',
  attachTo: {
    element: '#button-start',
    on: 'bottom'
  }
});

tour.start();

В этом примере подсказка появляется под кнопкой с id button-start.

Привязка к элементу через HTMLElement:

const targetElement = document.querySelector('.menu-item');

tour.addStep({
  id: 'step-2',
  text: 'Выбранный элемент меню',
  attachTo: {
    element: targetElement,
    on: 'right'
  }
});

Здесь используется прямой доступ к DOM-элементу, что удобно, если селектор не уникален или создается динамически.

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

Опция on: 'auto' позволяет Shepherd.js самостоятельно выбирать наиболее подходящее место для подсказки с учетом доступного пространства на экране. Это особенно полезно для адаптивного дизайна:

tour.addStep({
  id: 'step-3',
  text: 'Автоматическое позиционирование',
  attachTo: {
    element: '#dynamic-element',
    on: 'auto'
  }
});

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

Особенности работы с attachTo

  1. Обязательная привязка: Если шаг не привязан к элементу, подсказка будет отображаться в центре окна по умолчанию.
  2. Плавное позиционирование: Shepherd.js использует Popper.js для расчета позиции, что гарантирует корректное отображение даже при изменении размеров окна или скролле.
  3. Синхронизация с DOM: Если элемент привязки скрыт или удален из DOM, подсказка автоматически скрывается.
  4. Использование с кастомными классами: Можно добавлять CSS-классы к подсказке через classes для управления стилем и анимацией, не влияя на attachTo.

Комбинация с другими опциями шага

  • scrollTo: позволяет прокрутить страницу к элементу перед отображением подсказки.
tour.addStep({
  id: 'step-4',
  text: 'Шаг с прокруткой',
  attachTo: {
    element: '.footer-link',
    on: 'top'
  },
  scrollTo: true
});
  • beforeShowPromise: дает возможность выполнять асинхронные действия перед показом шага, например, динамически рендерить элемент, к которому будет привязан шаг.
tour.addStep({
  id: 'step-5',
  text: 'Асинхронная подготовка',
  attachTo: {
    element: '#async-element',
    on: 'bottom'
  },
  beforeShowPromise: () => new Promise(resolve => {
    setTimeout(resolve, 500); // ждем 500мс
  })
});

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

  • Стараться использовать уникальные селекторы или прямой доступ к HTMLElement, чтобы избежать ошибок при динамически изменяемой разметке.
  • Для сложных интерфейсов с динамическими элементами лучше сочетать attachTo с beforeShowPromise и scrollTo.
  • Использовать on: 'auto' для адаптивных интерфейсов и мобильных версий страниц, чтобы подсказки не перекрывали важный контент.

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

Оглавление