XSS и санитизация контента

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

Инициализация Shepherd.js

Создание нового тура начинается с подключения библиотеки и создания экземпляра класса Shepherd.Tour:

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

Пояснения:

  • scrollTo: true — автоматически прокручивает страницу к текущему шагу.
  • cancelIcon.enabled: true — отображает кнопку закрытия тура.
  • classes — задает тему оформления, можно использовать встроенные темы или создавать свои.

Добавление шагов в тур

Каждый шаг определяется методом addStep:

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в наш интерактивный тур!',
  attachTo: {
    element: '.header-logo',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Ключевые элементы шага:

  • id — уникальный идентификатор шага.
  • text — содержимое подсказки. Может включать HTML.
  • attachTo — объект, указывающий элемент страницы и позицию подсказки.
  • buttons — массив кнопок с действиями, такими как tour.next и tour.back.

Навигация и управление туром

Shepherd.js предоставляет методы для управления туром:

  • tour.start() — запуск тура.
  • tour.next() — переход к следующему шагу.
  • tour.back() — возврат к предыдущему шагу.
  • tour.cancel() — завершение тура до конца.

Настройка внешнего вида

Каждый шаг можно стилизовать отдельно, используя CSS классы:

tour.addStep({
  id: 'feature-step',
  text: 'Это важная функция.',
  classes: 'custom-step highlight-step'
});

Возможности:

  • classes — применяет пользовательские CSS классы.
  • Настройка фонового цвета, теней, стрелок, размера подсказки.

Динамические шаги и события

Shepherd.js поддерживает динамическое создание шагов на основе состояния приложения:

if (user.isAdmin) {
  tour.addStep({
    id: 'admin-panel',
    text: 'Панель администратора доступна только для администраторов.',
    attachTo: { element: '#admin-panel', on: 'right' },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
}

События позволяют выполнять код при начале или завершении шага:

tour.on('show', (event) => {
  console.log('Показан шаг:', event.step.id);
});

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

Интеграция с динамическим контентом

Shepherd.js корректно работает с элементами, которые появляются на странице после загрузки:

const step = {
  id: 'dynamic-step',
  text: 'Это шаг для динамически созданного элемента.',
  attachTo: { element: '#dynamic-element', on: 'top' },
  buttons: [{ text: 'Далее', action: tour.next }]
};

document.addEventListener('DOMContentLoaded', () => {
  if (document.querySelector('#dynamic-element')) {
    tour.addStep(step);
  }
});

Локализация и мультиязычность

Текст шагов можно хранить в объекте локализации:

const translations = {
  en: { welcome: 'Welcome to the tour' },
  ru: { welcome: 'Добро пожаловать в тур' }
};

tour.addStep({
  id: 'intro',
  text: translations.ru.welcome,
  buttons: [{ text: 'Далее', action: tour.next }]
});

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

Управление сложными маршрутами

Для больших приложений удобно строить маршруты с условными переходами:

tour.addStep({
  id: 'step1',
  text: 'Шаг 1',
  buttons: [
    { text: 'Пропустить', action: () => tour.show('step3') },
    { text: 'Далее', action: tour.next }
  ]
});

Так можно пропускать шаги, адаптируя тур под разные сценарии использования.

Поддержка мультимедийного контента

Shepherd.js позволяет вставлять HTML, включая изображения и видео:

tour.addStep({
  id: 'video-step',
  text: `<p>Смотрите видео ниже:</p><video controls src="tutorial.mp4"></video>`,
  buttons: [{ text: 'Далее', action: tour.next }]
});

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

Производительность и оптимизация

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

Расширяемость и кастомные плагины

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

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

Оглавление