Отступы и смещения

Shepherd.js предоставляет гибкую систему управления расположением всплывающих подсказок относительно целевых элементов на странице. Центральными понятиями здесь являются отступы (padding) и смещения (offset), которые позволяют точно настраивать позиционирование подсказки для обеспечения удобного визуального восприятия.

Отступы (padding)

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

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

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

tour.addStep({
  id: 'example-step',
  text: 'Пример подсказки с отступами',
  attachTo: {
    element: '#myButton',
    on: 'bottom'
  },
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: {
          padding: 20
        }
      }
    ]
  }
});

tour.start();

В данном примере используется модификатор preventOverflow, который предотвращает выход подсказки за границы окна. Параметр padding задаёт внутренний отступ, влияющий на расчёт позиции подсказки.

Особенности:

  • Значение padding может быть числом (одинаковое для всех сторон) или объектом с отдельными значениями для каждой стороны:
padding: { top: 10, bottom: 15, left: 20, right: 20 }
  • Shepherd.js использует библиотеку Popper.js для позиционирования, поэтому все возможности Popper.js в части отступов доступны напрямую через popperOptions.

Смещения (offset)

Смещение позволяет сдвигать подсказку относительно её базовой позиции. В отличие от отступов, которые ограничивают подсказку рамками окна, смещения управляют точкой, где подсказка появляется относительно элемента.

Пример настройки смещения:

tour.addStep({
  id: 'offset-step',
  text: 'Подсказка с индивидуальным смещением',
  attachTo: {
    element: '#myButton',
    on: 'top'
  },
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: {
          offset: [0, 15] // [смещение по горизонтали, смещение по вертикали]
        }
      }
    ]
  }
});

Объяснение:

  • Первое значение массива offset отвечает за горизонтальное смещение (x), второе — за вертикальное (y).
  • Положительные значения сдвигают подсказку вниз и вправо, отрицательные — вверх и влево.
  • Смещение работает совместно с attachTo.on — направление базовой позиции подсказки сохраняется, но добавляется указанный сдвиг.

Комбинирование отступов и смещений

Для идеального позиционирования часто применяют одновременно и padding, и offset. Например, при наведении на кнопку в правом верхнем углу экрана:

tour.addStep({
  id: 'combined-step',
  text: 'Комбинация отступов и смещения',
  attachTo: {
    element: '#cornerButton',
    on: 'right'
  },
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: { padding: { top: 10, bottom: 10, left: 5, right: 5 } }
      },
      {
        name: 'offset',
        options: { offset: [10, 20] }
      }
    ]
  }
});

Здесь:

  • preventOverflow с padding гарантирует, что подсказка не уйдёт за экран.
  • offset сдвигает подсказку вправо на 10px и вниз на 20px относительно базовой позиции right.

Важные моменты при настройке

  1. Контекстные различия: если элемент находится внутри контейнера с прокруткой, значения смещения и отступов могут вести себя иначе, потому что Popper.js рассчитывает позицию относительно видимой области.
  2. Совместимость с scrollTo: при автоматической прокрутке к элементу стоит учитывать смещения, иначе подсказка может оказаться слишком близко к краю.
  3. Тема и визуальные рамки: стили подсказки могут влиять на восприятие смещений. Например, стрелки и паддинги внутри темы могут добавлять дополнительное визуальное пространство.

Практические советы

  • Всегда проверять подсказку на разных разрешениях экрана при заданных отступах и смещениях.
  • Для элементов, расположенных близко к краям экрана, использовать более высокие значения padding в preventOverflow.
  • Смещение удобно использовать для небольших корректировок позиции стрелки подсказки или смещения текста, не меняя основной ориентации подсказки (top, bottom, left, right).

Итоговые рекомендации по использованию

  • Отступы обеспечивают безопасное расположение подсказки внутри видимой области.
  • Смещения позволяют тонко подправить позицию относительно целевого элемента.
  • Комбинация этих двух инструментов обеспечивает максимальный контроль над внешним видом и удобством подсказок.

Использование popperOptions с модификаторами preventOverflow и offset является стандартной практикой для продвинутой настройки всех шагов туров в Shepherd.js.

Оглавление