Интеграция с Angular

Для интеграции Shepherd.js с Angular необходимо сначала установить библиотеку через npm:

npm install shepherd.js

Также потребуется установка стилей Shepherd:

npm install shepherd.js/dist/css/shepherd.css

После установки нужно подключить CSS в глобальные стили Angular, например, в angular.json:

"styles": [
  "src/styles.css",
  "node_modules/shepherd.js/dist/css/shepherd.css"
]

Импорт и настройка в компоненте

В Angular компонентах Shepherd импортируется следующим образом:

import { Component, OnInit } from '@angular/core';
import Shepherd from 'shepherd.js';

@Component({
  selector: 'app-tour',
  templateUrl: './tour.component.html',
  styleUrls: ['./tour.component.css']
})
export class TourComponent implements OnInit {
  private tour: Shepherd.Tour;

  ngOnInit(): void {
    this.initializeTour();
  }

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

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

    this.tour.addStep({
      id: 'step-2',
      text: 'Здесь находятся основные функции.',
      attachTo: { element: '.features', on: 'right' },
      buttons: [
        {
          text: 'Назад',
          action: this.tour.back
        },
        {
          text: 'Завершить',
          action: this.tour.complete
        }
      ]
    });
  }

  startTour(): void {
    this.tour.start();
  }
}

Привязка к шаблону

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

<button class="start-button" (click)="startTour()">Начать тур</button>

<div class="features">
  <!-- Содержимое функциональных блоков -->
</div>

Использование модулей Angular для повторного использования тура

Для удобного повторного использования можно создать Angular-сервис, который будет управлять туром. Это позволяет централизовать логику и избежать дублирования кода в нескольких компонентах:

import { Injectable } from '@angular/core';
import Shepherd from 'shepherd.js';

@Injectable({
  providedIn: 'root'
})
export class TourService {
  private tour: Shepherd.Tour;

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

    this.setupSteps();
  }

  private setupSteps(): void {
    this.tour.addStep({
      id: 'intro',
      text: 'Это первый шаг тура.',
      attachTo: { element: '.intro', on: 'bottom' },
      buttons: [
        { text: 'Далее', action: this.tour.next }
      ]
    });

    this.tour.addStep({
      id: 'details',
      text: 'Дополнительная информация отображается здесь.',
      attachTo: { element: '.details', on: 'top' },
      buttons: [
        { text: 'Назад', action: this.tour.back },
        { text: 'Завершить', action: this.tour.complete }
      ]
    });
  }

  startTour(): void {
    this.tour.start();
  }
}

Компонент теперь может вызывать тур через сервис:

constructor(private tourService: TourService) {}

startTour(): void {
  this.tourService.startTour();
}

Настройка стилей и тем оформления

Shepherd позволяет менять темы через CSS-классы. Для Angular-проектов можно добавить собственный файл стилей и переопределить стандартные классы:

.shepherd-theme-arrows .shepherd-content {
  background-color: #f0f0f0;
  color: #333;
}

.shepherd-theme-arrows .shepherd-button {
  background-color: #007bff;
  color: white;
}

Подключение собственного CSS позволяет сохранять единый стиль приложения.

Работа с динамическим контентом

Если элементы страницы создаются динамически через Angular ngIf или ngFor, важно запускать тур только после рендеринга этих элементов. Для этого можно использовать AfterViewInit и setTimeout для гарантии наличия элементов в DOM:

import { AfterViewInit } from '@angular/core';

export class TourComponent implements AfterViewInit {
  ngAfterViewInit(): void {
    setTimeout(() => {
      this.startTour();
    });
  }
}

Интеграция с роутингом Angular

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

import { Router, NavigationEnd } from '@angular/router';

constructor(private router: Router) {
  this.router.events.subscribe(event => {
    if (event instanceof NavigationEnd) {
      // Обновление текущего шага тура или его запуск
      this.tour.show('step-2');
    }
  });
}

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

Shepherd.js поддерживает кастомные кнопки с пользовательской логикой:

this.tour.addStep({
  id: 'custom-step',
  text: 'Пример с кастомной кнопкой.',
  attachTo: { element: '.custom', on: 'bottom' },
  buttons: [
    {
      text: 'Выполнить действие',
      action: () => {
        console.log('Действие выполнено');
        this.tour.next();
      }
    }
  ]
});

Это позволяет создавать интерактивные и адаптивные обучающие последовательности внутри Angular-приложения.

Управление состоянием и сохранение прогресса

Для сложных туров полезно сохранять состояние пользователя в localStorage или через сервис:

if (!localStorage.getItem('tourCompleted')) {
  this.startTour();
}

this.tour.on('complete', () => {
  localStorage.setItem('tourCompleted', 'true');
});

Такой подход предотвращает повторный запуск тура при последующих визитах пользователя и позволяет контролировать прогресс.

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

Оглавление