Builder для конфигурации

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

Инициализация Builder

Для начала требуется создать экземпляр Shepherd Tour:

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

Здесь defaultStepOptions задаёт базовые параметры, которые будут применяться ко всем шагам, если не указано иное. Это упрощает конфигурацию и уменьшает дублирование кода.

Добавление шагов через Builder

Каждый шаг создаётся с помощью метода addStep, принимающего имя шага и объект конфигурации:

tour.addStep('intro', {
  text: 'Добро пожаловать в наш интерфейс!',
  attachTo: { element: '#start-button', on: 'bottom' },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Ключевые параметры шагов:

  • text — основной текст шага.
  • attachTo — объект с указанием DOM-элемента (element) и позиции подсказки (on).
  • buttons — массив кнопок с действиями (action), такими как next, back, cancel.

Методы Builder для тонкой настройки

Builder позволяет модифицировать шаги после их создания и динамически управлять поведением тура.

  • Установка кастомного класса:
tour.getById('intro').updateStepOptions({
  classes: 'custom-step-style'
});
  • Изменение текста или элементов динамически:
tour.getById('intro').updateStepOptions({
  text: 'Новый текст шага после события'
});
  • Управление событиями:
tour.on('show', function() {
  console.log('Шаг отображен');
});

tour.on('complete', function() {
  console.log('Тур завершен');
});

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

Настройка переходов между шагами

Переходы между шагами можно контролировать через свойства кнопок и события:

buttons: [
  {
    text: 'Назад',
    action: tour.back
  },
  {
    text: 'Пропустить',
    action: tour.cancel
  },
  {
    text: 'Далее',
    action: function() {
      if (условие) {
        tour.next();
      } else {
        tour.show('special-step');
      }
    }
  }
]

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

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

Builder поддерживает добавление любой кастомной логики внутри шагов. Например, можно добавить обработчик клика на внешний элемент:

tour.addStep('custom', {
  text: 'Нажмите на кнопку, чтобы продолжить',
  attachTo: { element: '#action-button', on: 'top' },
  buttons: [],
  when: {
    show: function() {
      document.querySelector('#action-button').addEventListener('click', tour.next);
    }
  }
});

Свойство when позволяет привязывать функции к событиям show, hide, complete, обеспечивая полный контроль над жизненным циклом шага.

Динамическое создание шагов через Builder

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

const stepsData = [
  { text: 'Шаг 1', element: '#step1' },
  { text: 'Шаг 2', element: '#step2' },
  { text: 'Шаг 3', element: '#step3' }
];

stepsData.forEach((data, index) => {
  tour.addStep(`step-${index + 1}`, {
    text: data.text,
    attachTo: { element: data.element, on: 'bottom' },
    buttons: [
      { text: 'Далее', action: tour.next },
      { text: 'Назад', action: tour.back }
    ]
  });
});

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

Встроенные методы управления Builder

  • start() — запускает тур.
  • next() — переходит к следующему шагу.
  • back() — возвращает к предыдущему шагу.
  • cancel() — завершает тур досрочно.
  • complete() — завершает тур корректно.
  • getById(id) — возвращает объект шага для динамических изменений.

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

Сочетание с кастомной логикой UI

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

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

Оглавление