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

Для начала необходимо добавить библиотеку Intro.js в проект Angular. Наиболее удобный способ — использование npm:

npm install intro.js --save
npm install @types/intro.js --save-dev

После установки нужно подключить CSS и JS файлы в Angular. В angular.json в раздел styles и scripts добавляются пути к файлам библиотеки:

"styles": [
  "node_modules/intro.js/minified/introjs.min.css",
  "src/styles.css"
],
"scripts": [
  "node_modules/intro.js/minified/intro.min.js"
]

Также можно импортировать библиотеку напрямую в компоненты через TypeScript:

import * as introJs from 'intro.js/intro.js';

Создание сервиса для управления турами

Для удобного использования Intro.js в приложении Angular рекомендуется создать сервис. Это позволит централизованно управлять всеми турами и настройками.

import { Injectable } from '@angular/core';
import * as introJs from 'intro.js/intro.js';

@Injectable({
  providedIn: 'root'
})
export class TourService {

  private intro: any;

  constructor() {
    this.intro = introJs();
  }

  startTour(steps: any[], options: any = {}) {
    this.intro.setOptions({
      steps: steps,
      ...options
    });
    this.intro.start();
  }

  exitTour() {
    this.intro.exit();
  }

  nextStep() {
    this.intro.nextStep();
  }

  previousStep() {
    this.intro.previousStep();
  }
}

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

Настройка шагов тура

Каждый шаг тура в Intro.js задаётся объектом со следующими ключами:

element — селектор или элемент DOM, к которому привязан шаг.
intro — текст описания шага.
position — позиция подсказки относительно элемента (top, right, bottom, left).
tooltipClass — дополнительный CSS класс для стилизации подсказки.
highlightClass — класс для подсветки элемента.

Пример массива шагов:

const tourSteps = [
  {
    element: '#step1',
    intro: 'Это первый шаг нашего тура',
    position: 'bottom'
  },
  {
    element: '#step2',
    intro: 'Второй шаг с подсказкой сверху',
    position: 'top'
  },
  {
    element: '#step3',
    intro: 'Заключительный шаг, справа',
    position: 'right'
  }
];

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

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

import { Component } from '@angular/core';
import { TourService } from './tour.service';

@Component({
  selector: 'app-dashboard',
  templateUrl: './dashboard.component.html'
})
export class DashboardComponent {

  constructor(private tourService: TourService) {}

  startDashboardTour() {
    const steps = [
      { element: '#menu', intro: 'Навигационное меню', position: 'right' },
      { element: '#stats', intro: 'Основная статистика', position: 'bottom' },
      { element: '#profile', intro: 'Ваш профиль', position: 'left' }
    ];

    this.tourService.startTour(steps, { showProgress: true, showStepNumbers: true });
  }
}

Использование событий Intro.js

Intro.js поддерживает события, на которые можно подписываться для более сложной логики:

onbeforechange — перед переходом к следующему шагу.
onafterchange — после отображения нового шага.
oncomplete — завершение тура.
onexit — выход из тура пользователем.

Пример подключения событий через сервис:

this.tourService['intro'].onbeforechange((targetElement) => {
  console.log('Переход к элементу:', targetElement);
});

this.tourService['intro'].oncomplete(() => {
  console.log('Тур завершен');
});

Динамическая генерация шагов

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

generateStepsForCards(cards: any[]) {
  return cards.map((card, index) => ({
    element: `#card-${index}`,
    intro: `Карточка ${card.title}`,
    position: 'bottom'
  }));
}

Настройка визуального оформления

Intro.js позволяет кастомизировать внешний вид подсказок и подсвечиваемых элементов:

tooltipClass — добавление собственного класса к подсказке.
highlightClass — кастомизация подсветки элементов.
CSS переменные можно использовать для глобальной стилизации:

.introjs-tooltip {
  background-color: #1a73e8;
  color: white;
  font-size: 14px;
}

.introjs-helperLayer {
  border-radius: 8px;
  box-shadow: 0 0 10px rgba(0,0,0,0.3);
}

Поддержка модульного Angular подхода

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

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { TourService } from './tour.service';

@NgModule({
  imports: [CommonModule],
  providers: [TourService]
})
export class TourModule {}

После этого сервис доступен через инжекцию в любом компоненте, подключенном к модулю.

Работа с ленивой загрузкой модулей

Intro.js корректно работает с ленивыми модулями Angular. Нужно убедиться, что шаги тура определены только после рендеринга элементов DOM, иначе библиотека не сможет найти элементы. Для этого используется ngAfterViewInit или setTimeout:

ngAfterViewInit() {
  setTimeout(() => {
    this.tourService.startTour(this.steps);
  }, 0);
}

Поддержка мобильных устройств

Intro.js автоматически адаптируется под мобильные устройства, но рекомендуется использовать меньшие размеры подсказок и проверять позицию элементов. Настройки scrollToElement и overlayOpacity помогают улучшить UX:

this.tourService.startTour(this.steps, {
  scrollToElement: true,
  overlayOpacity: 0.5
});

Локализация текста подсказок

Intro.js позволяет менять текст кнопок и подсказок через опции nextLabel, prevLabel, skipLabel, doneLabel:

this.tourService.startTour(this.steps, {
  nextLabel: 'Далее',
  prevLabel: 'Назад',
  skipLabel: 'Пропустить',
  doneLabel: 'Готово'
});

Это особенно полезно для мультиязычных приложений.