Обработка overflow

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

Параметр tetherOptions

Shepherd изначально использует библиотеку Tether для позиционирования подсказок относительно элементов DOM. В объекте конфигурации шага можно определить поведение при переполнении:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    tetherOptions: {
      constraints: [
        {
          to: 'window',
          attachment: 'together',
          pin: true
        }
      ]
    }
  }
});

Ключевые моменты:

  • to: элемент или контейнер, к которому привязывается шаг ('window', 'scrollParent', CSS-селектор или DOM-элемент).
  • attachment: способ привязки тултипа к элементу ('top', 'bottom', 'left', 'right', с модификаторами 'start', 'end').
  • pin: логическое значение, разрешающее закрепление шага в пределах контейнера при переполнении.

Использование tetherOptions.constraints позволяет контролировать, что шаг никогда не выйдет за пределы указанного контейнера.

Использование popperOptions в Shepherd.js v8+

Начиная с версии 8, Shepherd.js интегрируется с библиотекой Popper.js для позиционирования, что даёт более гибкое управление overflow. Параметр popperOptions позволяет задавать поведение подсказки при нехватке места:

tour.addStep({
  id: 'example-step',
  text: 'Это пример шага с управлением overflow.',
  attachTo: { element: '.example', on: 'bottom' },
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: {
          boundary: 'viewport', // можно указать любое DOM-узел
          padding: 8
        }
      },
      {
        name: 'flip',
        options: {
          fallbackPlacements: ['top', 'right', 'left']
        }
      }
    ]
  }
});

Особенности модификаторов:

  • preventOverflow: предотвращает выход тултипа за границы контейнера (viewport, родительский элемент или кастомный контейнер).
  • padding: отступ от границы контейнера для безопасного отображения подсказки.
  • flip: автоматически меняет позицию шага при нехватке места, используя массив fallbackPlacements.

Комбинирование tetherOptions и popperOptions

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    tetherOptions: {
      constraints: [
        { to: 'window', attachment: 'together', pin: true }
      ]
    },
    popperOptions: {
      modifiers: [
        { name: 'preventOverflow', options: { boundary: 'viewport', padding: 10 } },
        { name: 'flip', options: { fallbackPlacements: ['top', 'right'] } }
      ]
    }
  }
});

Принудительное управление overflow через CSS

Иногда поведение библиотек недостаточно, и требуется дополнительная настройка через CSS:

.shepherd-element {
  max-width: 300px;
  overflow-wrap: break-word;
  word-break: break-word;
}

Важные моменты:

  • max-width ограничивает ширину тултипа, что предотвращает горизонтальное переполнение.
  • overflow-wrap и word-break обеспечивают корректное перенесение длинных слов.

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

Для интерфейсов с изменяющимся контентом полезно использовать метод updateStepElementPosition:

tour.getCurrentStep().updateStepElementPosition();

Это заставляет шаг пересчитать своё положение, учитывая текущее расположение элемента и состояние overflow. Особенно актуально при открытии модальных окон или изменении размеров окна.

Выводы по управлению overflow

  1. Shepherd.js поддерживает автоматическое предотвращение переполнения через Tether и Popper.
  2. Настройка через tetherOptions.constraints подходит для статичных интерфейсов.
  3. popperOptions дают динамическое управление, позволяя использовать модификаторы preventOverflow и flip.
  4. Дополнение CSS-правилами обеспечивает контроль над текстом и размером подсказок.
  5. Методы обновления позиции шага позволяют адаптироваться к динамическому контенту.

Эта комбинация инструментов делает управление overflow в Shepherd.js гибким и надежным даже для сложных интерфейсов с ограниченным пространством.

Оглавление