Контекст выполнения

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

Определение и назначение context

Каждый шаг в Shepherd.js создается через объект с настройками, где одной из ключевых опций является attachTo и when. Контекст выполнения позволяет:

  • Указывать, к какому элементу DOM привязан шаг (attachTo.element).
  • Определять, что должно произойти перед отображением шага (beforeShowPromise) или после его скрытия (when.hide).
  • Обеспечивать динамическое вычисление позиции и содержимого шага в зависимости от состояния приложения.

Пример базового шага с контекстом:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true,
    cancelIcon: { enabled: true }
  }
});

tour.addStep({
  id: 'example-step',
  text: 'Этот шаг привязан к кнопке.',
  attachTo: {
    element: '#my-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Здесь контекст выполнения шагa определяется привязкой к элементу #my-button и положением bottom.

Динамическое управление контекстом

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

tour.addStep({
  id: 'dynamic-step',
  text: () => `Сейчас время: ${new Date().toLocaleTimeString()}`,
  attachTo: {
    element: () => document.querySelector('.dynamic-element'),
    on: 'right'
  }
});

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

  • text может быть функцией, возвращающей строку. Значение будет вычислено при показе шага.
  • attachTo.element может быть функцией, возвращающей актуальный элемент DOM. Это важно для элементов, создающихся динамически после загрузки страницы.

Обработка событий шага через контекст

Shepherd.js предоставляет возможность привязывать события к шагу с помощью объекта when. Основные события:

  • show — вызывается при отображении шага.
  • hide — вызывается при скрытии шага.
  • complete — вызывается при завершении шага.
  • cancel — вызывается при отмене шага.

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

tour.addStep({
  id: 'event-step',
  text: 'Шаг с событиями',
  attachTo: { element: '#event-button', on: 'top' },
  when: {
    show: () => console.log('Шаг показан'),
    hide: () => console.log('Шаг скрыт')
  }
});

Это позволяет строить интерактивный контекст, когда шаги реагируют на действия пользователя или изменения интерфейса.

Асинхронный контекст с beforeShowPromise

Иногда шаг нельзя показывать мгновенно — необходимо дождаться, пока элемент появится в DOM или выполнится асинхронная операция. Для этого используется beforeShowPromise, возвращающий Promise:

tour.addStep({
  id: 'async-step',
  text: 'Шаг с ожиданием элемента',
  attachTo: { element: '#async-button', on: 'left' },
  beforeShowPromise: () => {
    return new Promise(resolve => {
      const check = setInterval(() => {
        if (document.querySelector('#async-button')) {
          clearInterval(check);
          resolve();
        }
      }, 100);
    });
  }
});

Этот подход гарантирует, что шаг не будет отображён до того момента, когда элемент станет доступен, что особенно важно для SPA-приложений с динамическим рендерингом.

Комбинирование контекстов для сложных сценариев

Shepherd.js позволяет объединять несколько механизмов контекста в одном шаге:

  • Динамический элемент через функцию в attachTo.element.
  • Актуальный текст через функцию в text.
  • Асинхронная подготовка шага через beforeShowPromise.
  • Обработка событий через when.

Пример комплексного шага:

tour.addStep({
  id: 'complex-step',
  text: () => `Сегодня ${new Date().toLocaleDateString()}`,
  attachTo: {
    element: () => document.querySelector('.user-card'),
    on: 'bottom'
  },
  beforeShowPromise: () => fetch('/api/status')
    .then(res => res.json())
    .then(data => {
      if (!data.active) {
        document.querySelector('.user-card').classList.add('inactive-highlight');
      }
    }),
  when: {
    hide: () => console.log('Пользователь видел шаг')
  },
  buttons: [
    { text: 'Далее', action: tour.next }
  ]
});

В этом примере шаг учитывает состояние сервера и изменяет внешний вид элемента перед показом, при этом отслеживает события скрытия шага.

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

  1. Привязка к элементу (attachTo) — основной механизм контекста, определяет позицию и объект для шага.
  2. Динамическое вычисление — функции для текста и элементов позволяют адаптировать шаг под текущую страницу.
  3. Асинхронная подготовка (beforeShowPromise) — гарантирует корректное отображение шагов в динамических интерфейсах.
  4. Обработка событий (when) — позволяет реагировать на действия пользователя и управлять туром в реальном времени.

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

Оглавление