Обертки и адаптеры

Shepherd.js — это мощная библиотека для создания интерактивных пошаговых руководств (туров) на веб-страницах. Для эффективного управления различными платформами и фреймворками используются обертки (wrappers) и адаптеры (adapters). Они позволяют интегрировать Shepherd.js в существующую инфраструктуру без прямого изменения базового кода библиотеки.

Обертки (Wrappers)

Обертка — это слой кода, который инкапсулирует логику Shepherd.js и предоставляет упрощённый интерфейс для взаимодействия. Основные цели оберток:

  • Сокрытие сложности создания и управления шагами тура.
  • Унификация работы с различными DOM-структурами.
  • Добавление дополнительной логики, специфичной для проекта (например, условное отображение шагов или динамическое вычисление селекторов элементов).

Пример обертки для создания базового тура:

class TourWrapper {
    constructor() {
        this.tour = new Shepherd.Tour({
            defaultStepOptions: {
                cancelIcon: {
                    enabled: true
                },
                scrollTo: { beh * avior: 'smooth', block: 'center' }
            }
        });
    }

    addStep(id, options) {
        this.tour.addStep({
            id,
            ...options
        });
    }

    start() {
        this.tour.start();
    }

    next() {
        this.tour.next();
    }

    cancel() {
        this.tour.cancel();
    }
}

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

Адаптеры (Adapters)

Адаптер — это посредник между Shepherd.js и сторонними библиотеками или фреймворками (React, Angular, Vue). Адаптер обеспечивает:

  • Совместимость с системой управления состоянием фреймворка.
  • Возможность рендерить шаги в виртуальном DOM.
  • Автоматическую синхронизацию событий (например, открытие и закрытие шагов при изменении состояния компонента).

Пример адаптера для интеграции с React:

import { useEffect } from 'react';
import Shepherd from 'shepherd.js';

export function useShepherdTour(steps) {
    useEffect(() => {
        const tour = new Shepherd.Tour({
            defaultStepOptions: {
                cancelIcon: { enabled: true },
                scrollTo: { beh * avior: 'smooth', block: 'center' }
            }
        });

        steps.forEach(step => tour.addStep(step));

        tour.start();

        return () => tour.cancel();
    }, [steps]);
}

Здесь useShepherdTour позволяет автоматически запускать и останавливать тур при изменении данных в React-компоненте, обеспечивая реактивность и совместимость с жизненным циклом компонента.

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

Часто шаги тура не статичны и зависят от состояния страницы или пользователя. Обертки и адаптеры позволяют создавать шаги динамически:

function generateSteps(userRole) {
    const steps = [
        {
            id: 'welcome',
            text: 'Добро пожаловать!',
            attachTo: { element: '#header', on: 'bottom' }
        }
    ];

    if (userRole === 'admin') {
        steps.push({
            id: 'admin-panel',
            text: 'Это панель администратора',
            attachTo: { element: '#adminPanel', on: 'right' }
        });
    }

    return steps;
}

const tour = new TourWrapper();
generateSteps('admin').forEach(step => tour.addStep(step.id, step));
tour.start();

Таким образом, обертки позволяют адаптировать шаги под конкретного пользователя или текущие условия, сохраняя при этом чистоту и читаемость кода.

Расширение функционала через обертки

Обертки могут внедрять новые возможности поверх стандартного API Shepherd.js:

  • Логирование действий пользователя на каждом шаге.
  • Автоматическая проверка условий для пропуска определённых шагов.
  • Поддержка мультиязычности за счёт обертки, которая подставляет тексты шагов в зависимости от локали.

Пример обертки с логированием:

class LoggingTourWrapper extends TourWrapper {
    addStep(id, options) {
        const step = { id, ...options };
        const originalShow = step.show;
        step.show = () => {
            console.log(`Step ${id} показан`);
            if (originalShow) originalShow();
        };
        super.addStep(id, step);
    }
}

Совмещение оберток и адаптеров

На практике обертки и адаптеры часто используются вместе:

  • Обертка скрывает базовую конфигурацию и предоставляет API для управления турами.
  • Адаптер обеспечивает совместимость с конкретной платформой или фреймворком.
  • Вместе они создают масштабируемую, расширяемую систему для управления интерактивными турами.

Выводы о применении

Использование оберток и адаптеров в Shepherd.js позволяет:

  • Минимизировать повторение кода.
  • Легко внедрять туры в сложные приложения.
  • Поддерживать чистую архитектуру при работе с динамическим контентом и фреймворками.
  • Расширять функционал без изменения ядра библиотеки.

Обертки и адаптеры становятся фундаментальными инструментами при разработке корпоративных решений с многоуровневыми интерактивными руководствами и пользовательскими интерфейсами.

Оглавление