Неправильное позиционирование

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

Ключевые параметры позиционирования:

  • attachment – определяет точку крепления тултипа к целевому элементу. Возможные значения: top, bottom, left, right, а также их комбинации с start и end (top-start, bottom-end).
  • targetAttachment – указывает, к какой части целевого элемента привязывается тултип.
  • offset – смещение подсказки относительно точки привязки, задается как строка "x y" или массив [x, y].

Частые ошибки при позиционировании

  1. Неправильное использование attachment и targetAttachment Ошибка возникает, когда значения attachment и targetAttachment задаются одинаково, например top top. Это приводит к наложению тултипа на целевой элемент вместо выравнивания сверху.

  2. Отсутствие учета размеров элемента Если целевой элемент имеет динамическую ширину или высоту, жестко заданное смещение может вызвать частичное скрытие подсказки за пределами экрана.

  3. Игнорирование контейнера Shepherd.js по умолчанию рендерит тултипы в body. Если целевой элемент находится внутри scrollable контейнера, тултип может позиционироваться некорректно. Решение: использовать attachTo: { element: '.selector', on: 'top' } с опцией scrollTo: true и проверкой родительских overflow-свойств.

  4. Конфликт CSS стилей Пользовательские стили с position: relative или overflow: hidden на родительских элементах могут привести к сдвигу подсказки. Popper.js рассчитывает координаты относительно окна, а не родителя с overflow, поэтому необходимо корректировать стили или использовать modifiers Popper.js для смещения.

Настройка правильного позиционирования

  • Использовать attachTo для привязки к конкретному элементу:
tour.addStep({
  id: 'example-step',
  text: 'Подсказка с правильным позиционированием',
  attachTo: {
    element: '#target-element',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});
  • Применять popperOptions.modifiers для тонкой настройки:
popperOptions: {
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 10] // сдвиг на 10px вниз
      }
    },
    {
      name: 'preventOverflow',
      options: {
        boundary: 'viewport'
      }
    }
  ]
}
  • Включать scrollTo: true, если элемент может быть вне видимой области экрана.

Диагностика проблем позиционирования

  1. Проверка координат через DevTools Использовать инспектор и проверить координаты элемента и тултипа. Если тултип отображается за пределами экрана, необходимо скорректировать offset или attachment.

  2. Логирование Popper.js Включение modifiers.computeStyles.gpuAcceleration = false позволяет выявлять проблемы, связанные с 3D-трансформациями и смещением.

  3. Тестирование на разных разрешениях экрана Многие ошибки проявляются только при изменении размеров окна. Использование responsive настроек и динамических offset решает проблему.

Советы по предотвращению неправильного позиционирования

  • Всегда использовать комбинацию attachTo.on и popperOptions.modifiers.offset для точного контроля.
  • Проверять родительские элементы на наличие overflow: hidden или position: relative.
  • При динамическом контенте использовать метод tour.refreshStep() после изменения DOM.
  • Для элементов, которые появляются после события (например, модальные окна), добавлять шаг после их полной отрисовки.

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

Оглавление