getById

В библиотеке Shepherd.js метод getById предназначен для получения конкретного шага тура по его уникальному идентификатору. Этот метод особенно полезен при необходимости управления отдельными шагами после их создания, без обращения к массиву всех шагов напрямую.

Синтаксис метода

const step = tour.getById(id);
  • tour — объект тура, созданный через new Shepherd.Tour(options).
  • id — строка, уникальный идентификатор шага, который был задан при его создании.
  • Возвращаемое значение — объект шага (Shepherd.Step) с указанным id, либо undefined, если шаг с таким идентификатором не найден.

Присвоение идентификатора шагу

Каждый шаг тура в Shepherd.js может иметь свой уникальный идентификатор. Это делается при создании шага через метод addStep:

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

tour.addStep({
  id: 'intro',
  text: 'Это вводный шаг',
  attachTo: {
    element: '#start-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Идентификатор 'intro' в данном примере позволяет позднее получить доступ к этому шагу напрямую через getById.

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

  1. Получение шага для изменения текста или опций
const introStep = tour.getById('intro');
if (introStep) {
  introStep.updateStepOptions({
    text: 'Обновлённый текст для вводного шага'
  });
}

В данном примере метод updateStepOptions изменяет параметры уже созданного шага без необходимости пересоздавать его.

  1. Открытие шага по идентификатору
const step = tour.getById('intro');
if (step) {
  step.show();
}

Метод show() позволяет отобразить выбранный шаг, независимо от позиции текущего шага тура.

  1. Динамическое управление классами и стилями
const step = tour.getById('intro');
if (step) {
  step.getElement().classList.add('highlight-step');
}

Использование getElement() возвращает DOM-элемент шага, к которому можно применять любые стандартные методы работы с элементами страницы.

Важные особенности

  • Возвращаемый тип: getById всегда возвращает объект типа Shepherd.Step или undefined. Это позволяет использовать проверку существования шага перед его модификацией.
  • Уникальность идентификатора: Все шаги должны иметь уникальный id в пределах одного тура. Дублирование идентификаторов приведет к непредсказуемому поведению при вызове getById.
  • Работа с асинхронными шагами: Если шаг добавляется динамически в процессе работы тура, необходимо убедиться, что вызов getById происходит после его добавления.

Практические сценарии применения

  • Обновление текста шага в реальном времени — полезно для многошаговых форм или интерактивных подсказок, где контент меняется в зависимости от действий пользователя.
  • Программное переключение между шагами — можно получить нужный шаг по id и вызвать show(), создавая нелинейный поток тура.
  • Анимация или визуальная подсветка элементов — получение DOM-элемента шага позволяет применять CSS-классы, эффекты перехода или сторонние библиотеки анимации.

Рекомендации по структуре идентификаторов

  • Использовать понятные имена, отражающие содержимое шага (intro, form-step-1, confirmation).
  • Избегать пробелов и специальных символов.
  • Если тур большой, применять префиксы для групп шагов (settings-privacy, settings-notifications), чтобы облегчить поиск через getById.

Интеграция с другими методами Shepherd.js

Метод getById хорошо сочетается с:

  • updateStepOptions() — для изменения текста, кнопок, классов.
  • show() и hide() — для программного управления отображением шага.
  • destroy() — для удаления шага, если больше не нужен.
  • getElement() — для работы с DOM-структурой шага.

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

Оглавление