Интеграция с Popper.js

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

Подключение Popper.js

Shepherd.js автоматически интегрируется с Popper.js через свой пакет, если используется версия, включающая Popper. Для явного подключения можно использовать отдельный импорт:

import Shepherd from 'shepherd.js';
import { createPopper } from '@popperjs/core';

В этом случае Popper.js используется для расчета положения каждого шага относительно целевого элемента, обеспечивая:

  • Выравнивание подсказки (top, bottom, left, right).
  • Смещение через опцию offset.
  • Автоматический выбор позиции при недостатке места (flip).

Настройка позиции шагов

Каждый шаг Shepherd.js принимает объект attachTo, где можно указать целевой элемент и направление подсказки. Пример:

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

tour.addStep({
  id: 'step-1',
  text: 'Это подсказка к кнопке.',
  attachTo: {
    element: '#myButton',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

tour.start();

Ключевой момент — опция on, которая напрямую взаимодействует с Popper.js, задавая предпочтительное направление подсказки. Popper.js автоматически корректирует позицию при ограниченном пространстве.

Использование опций Popper.js через popperOptions

Shepherd.js позволяет передавать дополнительные параметры Popper.js через popperOptions:

tour.addStep({
  id: 'step-2',
  text: 'Подсказка с настройками Popper.js.',
  attachTo: { element: '#inputField', on: 'right' },
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: { offset: [0, 10] }
      },
      {
        name: 'preventOverflow',
        options: { padding: 8 }
      }
    ]
  }
});

Основные возможности popperOptions:

  • offset — смещение подсказки относительно целевого элемента. Первый параметр задает горизонтальное смещение, второй — вертикальное.
  • preventOverflow — предотвращает выход подсказки за пределы окна или контейнера.
  • flip — автоматически меняет позицию подсказки при недостатке места.
  • arrow — добавляет стрелку, указывающую на целевой элемент, с настройкой смещения.

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

Popper.js автоматически отслеживает изменения в DOM и пересчитывает позицию шагов. Для ручного обновления можно вызвать метод update() у шага:

const step = tour.addStep({
  id: 'dynamic-step',
  text: 'Динамическая подсказка',
  attachTo: { element: '#dynamicElement', on: 'top' }
});

step.show();

// После изменения размеров элемента или окна
step.popperInstance.update();

popperInstance — это внутренний объект Popper.js, создаваемый Shepherd.js для управления позицией текущей подсказки.

Работа с адаптивными интерфейсами

Popper.js позволяет автоматически подстраивать подсказки под размеры экрана. В Shepherd.js это реализуется через комбинацию опций flip и preventOverflow:

popperOptions: {
  modifiers: [
    { name: 'flip', options: { fallbackPlacements: ['top', 'right', 'bottom', 'left'] } },
    { name: 'preventOverflow', options: { padding: 10 } }
  ]
}
  • fallbackPlacements задает список альтернативных позиций, если основная недоступна.
  • padding определяет минимальное расстояние подсказки от границ окна.

Использование кастомных попперов

Для сложных интерфейсов можно создавать собственные экземпляры Popper.js и передавать их в Shepherd.js через опцию popperOptions.modifiers. Например, для позиционирования относительно родительского контейнера с фиксированной высотой:

popperOptions: {
  modifiers: [
    {
      name: 'computeStyles',
      options: { gpuAcceleration: false }
    },
    {
      name: 'preventOverflow',
      options: { boundary: '#parentContainer' }
    }
  ]
}

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

Итоговые рекомендации по интеграции

  • Использовать attachTo для базового позиционирования шагов.
  • При необходимости уточнять поведение Popper.js через popperOptions.
  • Использовать flip и preventOverflow для адаптивных интерфейсов.
  • При динамических изменениях DOM вызывать popperInstance.update() для корректного позиционирования.
  • Для сложных интерфейсов создавать кастомные модификаторы Popper.js, чтобы полностью контролировать поведение подсказок.

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

Оглавление