InteractiveDemo.tsx

Обзор

InteractiveDemo.tsx — это React-компонент, реализующий интерактивный демонстрационный тур по функциональности игрового приложения с разными сценариями для различных типов пользователей (персон). Цель файла — провести пользователя по последовательности шагов с подсказками, выделением элементов интерфейса и возможностью управления процессом показа (старт, пауза, сброс). Также компонент генерирует QR-код и мобильную ссылку для доступа к демо на мобильных устройствах, предоставляет режим самостоятельного изучения и отображает советы по использованию демо.

Основные сущности

Интерфейсы

interface DemoStep {
  id: string;             // Уникальный идентификатор шага
  title: string;          // Заголовок шага
  description: string;    // Описание шага
  action: string;         // Рекомендованное действие пользователя
  highlight: string;      // CSS-селектор для подсветки элемента интерфейса
  duration: number;       // Предполагаемая длительность шага в секундах
}

interface InteractiveDemoProps {
  onStepComplete: (stepId: string) => void; // Коллбек при завершении шага
  currentPersona: string;                    // Текущая персона (типа пользователя)
}

Компонент InteractiveDemo

Назначение

Главный React-компонент, управляющий логикой и отображением интерактивного демо-тура. В зависимости от переданной персоны, показывает соответствующий набор шагов, позволяет запускать, ставить на паузу, сбрасывать демонстрацию, отображает прогресс, подсвечивает интерфейс и генерирует QR-код для мобильного доступа.

Параметры

• onStepComplete(stepId: string): void — функция обратного вызова, вызываемая при завершении текущего шага с передачей его id.

• currentPersona: string — тип пользователя, определяющий набор шагов демо. Поддерживаются: 'casual_gamer', 'power_user', 'validator'.

Состояния (State)

• currentStep: number — индекс текущего шага в выбранном массиве шагов.

• isPlaying: boolean — флаг, указывающий, запущен ли тур.

• showTooltips: boolean — отображать ли подсказки (советы).

• qrCodeUrl: string — URL сгенерированного QR-кода для мобильного доступа.

• mobileUrl: string — URL для мобильного демо.

Внутренние данные

demoSteps

Объект, где ключ — персона, а значение — массив шагов DemoStep, описывающих последовательность действий демо.

Пример шага для casual_gamer:

{
  "id": "craft_sword",
  "title": "Craft Your First Weapon",
  "description": "Click 'Craft Sword' - notice how instant it is!",
  "action": "Click the Craft button",
  "highlight": "[data-action=\"craft\"]",
  "duration": 10
}

Методы и основные функции

startDemo() : void

Запускает демонстрацию, устанавливая isPlaying в true и currentStep в 0.

Использование:

<button onClick={startDemo}>Start Guided Tour</button>

pauseDemo() : void

Останавливает демонстрацию, устанавливая isPlaying в false.

resetDemo() : void

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

nextStep() : void

Переходит к следующему шагу демо. Если текущий шаг не последний — вызывает onStepComplete с id текущего шага и увеличивает currentStep. Если последний — останавливает демонстрацию и вызывает onStepComplete('demo_complete').

highlightElement(selector: string) : void

Подсвечивает элемент интерфейса, указанный CSS-селектором, добавляя класс demo-highlight. Перед этим убирает подсветку со всех элементов с этим классом.

Используемые хуки React

• useState — для управления локальным состоянием компонента.

• useEffect —

  • Генерация URL и QR-кода при смене currentPersona.

  • Подсветка текущего элемента при изменении currentStep или isPlaying.

Взаимодействия с другими частями системы

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

• Генерирует QR-код с помощью библиотеки qrcode для мобильного доступа.

• Использует иконки из lucide-react.

• Подсветка элементов UI осуществляется путем манипуляции DOM по CSS-селекторам, которые должны соответствовать другим компонентам приложения (например, кнопкам и блокам с data-action, data-section).

Особенности реализации и алгоритмы

• Для каждой персоны определён уникальный набор шагов с разной длительностью и элементами подсветки.

• Для выделения элементов используется добавление CSS-класса demo-highlight, при этом удаляется подсветка со всех других элементов.

• Прогресс отображается в виде прогресс-бара, ширина которого вычисляется как процентное отношение текущего шага к общему количеству.

• Поддержка переключения подсказок (tooltips) с сохранением состояния.

• Автоматическая генерация URL для мобильного режима с параметрами в query string.

• QR-код генерируется при монтировании компонента или смене персоны.

Использование

<InteractiveDemo
  currentPersona="casual_gamer"
  onStepComplete={(stepId) => console.log(`Step completed: ${stepId}`)}
/>

Визуальная структура компонента

componentDiagram
    InteractiveDemo <|-- DemoHeader
    InteractiveDemo <|-- CurrentStepDisplay
    InteractiveDemo <|-- DemoControls
    InteractiveDemo <|-- ProgressBar
    InteractiveDemo <|-- DemoStepsList
    InteractiveDemo <|-- MobileAccess
    InteractiveDemo <|-- TryItYourselfMode
    InteractiveDemo <|-- DemoTips

    DemoHeader : отображение заголовка и кнопка переключения подсказок
    CurrentStepDisplay : показывает текущий шаг, описание и кнопки "Complete Step" / "Pause"
    DemoControls : кнопки управления туром (старт, пауза, сброс)
    ProgressBar : визуализация прогресса демо
    DemoStepsList : список всех шагов с подсветкой текущего и выполненных
    MobileAccess : QR-код и мобильный URL для доступа к демо
    TryItYourselfMode : режим свободного изучения с рекомендациями
    DemoTips : блок с подсказками при включенном отображении

Итог

Компонент InteractiveDemo.tsx предоставляет комплексный, ориентированный на пользователя интерактивный тур с поддержкой нескольких пользовательских персон, позволяя последовательно демонстрировать функционал игрового приложения с подсветкой интерфейса, управлением прогрессом, мобильным доступом и советами. Его архитектура основана на управлении состоянием React с использованием хуков и динамической генерации шагов и QR-кодов, что обеспечивает удобство и гибкость интеграции в систему.