Добавление кастомных методов

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

Структура кастомного метода

Кастомный метод представляет собой функцию, которая может быть привязана к жизненному циклу шага. Основные жизненные циклы, поддерживаемые Driver.js:

  • onNext — вызывается при переходе к следующему шагу
  • onPrevious — вызывается при возврате к предыдущему шагу
  • onStart — вызывается при запуске всего тура
  • onEnd — вызывается после завершения тура
  • onHighlightStarted — вызывается, когда элемент подсвечен
  • onHighlighted — вызывается после завершения анимации подсветки

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

const driver = new Driver();

driver.defineSteps([
  {
    element: '#menuButton',
    popover: {
      title: 'Меню',
      description: 'Кнопка открывает главное меню.'
    },
    onNext: function() {
      console.log('Переход к следующему шагу выполнен.');
    }
  }
]);

driver.start();

В данном примере при клике на кнопку Next будет вызвана функция onNext, которая выполнит кастомный код.

Расширение стандартного API через defineMethod

Driver.js позволяет создавать собственные методы, которые можно использовать для всех шагов, а не только для одного. Это делается через метод Driver.defineMethod. Стандартный синтаксис:

Driver.defineMethod('myCustomAction', function(step) {
  // step — объект текущего шага
  console.log(`Выполняется кастомный метод для элемента: ${step.element}`);
});

После определения метода его можно вызывать в параметрах шагов:

driver.defineSteps([
  {
    element: '#searchInput',
    popover: {
      title: 'Поиск',
      description: 'Введите текст для поиска.'
    },
    myCustomAction: function(step) {
      step.element.style.border = '2px solid red';
    }
  }
]);

Ключевой момент: step.element всегда указывает на DOM-элемент, к которому привязан текущий шаг. Это позволяет динамически изменять его стиль, атрибуты или содержимое.

Передача аргументов в кастомные методы

Кастомные методы могут принимать аргументы для более гибкого поведения:

Driver.defineMethod('highlightWithColor', function(step, color) {
  step.element.style.backgroundColor = color;
});

// Использование метода с аргументом
driver.defineSteps([
  {
    element: '#profilePic',
    popover: {
      title: 'Аватар',
      description: 'Ваш профильный аватар.'
    },
    highlightWithColor: 'yellow'
  }
]);

В этом случае метод highlightWithColor применит желтую подсветку к элементу шага.

Встраивание асинхронной логики

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

Driver.defineMethod('fetchDataBeforeNext', function(step) {
  return fetch('/api/data')
    .then(response => response.json())
    .then(data => {
      console.log('Данные получены:', data);
    });
});

driver.defineSteps([
  {
    element: '#loadButton',
    popover: {
      title: 'Загрузка данных',
      description: 'Данные будут загружены перед следующим шагом.'
    },
    onNext: function(step) {
      return driver.fetchDataBeforeNext(step);
    }
  }
]);

Driver.js дождется выполнения промиса, прежде чем перейти к следующему шагу.

Интеграция кастомных методов с глобальными событиями

Кастомные методы можно использовать совместно с глобальными событиями Driver.js:

  • driver.on('start', callback) — запуск тура
  • driver.on('end', callback) — завершение тура
  • driver.on('highlight', callback) — подсветка элемента

Пример:

driver.on('highlight', step => {
  if(step.element.id === 'specialButton') {
    driver.customGlowEffect(step.element);
  }
});

Здесь customGlowEffect — это ранее определенный кастомный метод.

Лучшие практики при создании кастомных методов

  • Изоляция логики: каждый метод должен выполнять одну задачу, чтобы не создавать зависимости между шагами.
  • Обработка ошибок: внутри методов следует использовать блоки try/catch для предотвращения остановки тура из-за исключений.
  • Проверка DOM: перед манипуляцией с элементом нужно убедиться, что он существует (if (step.element)).
  • Асинхронная поддержка: возвращение промисов обеспечивает корректное ожидание операций.
  • Переиспользуемость: методы стоит определять через Driver.defineMethod, чтобы их можно было использовать в разных турах.

Примеры практических методов

  1. Показывать анимацию подсветки
Driver.defineMethod('pulseHighlight', function(step) {
  step.element.classList.add('pulse-animation');
});
  1. Автоматическая прокрутка к элементу
Driver.defineMethod('scrollToStep', function(step) {
  step.element.scrollIntoView({ beh * avior: 'smooth', block: 'center' });
});
  1. Динамическая смена содержимого поповера
Driver.defineMethod('updatePopoverContent', function(step, content) {
  step.popover.description = content;
  driver.refreshStep(step);
});

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

Оглавление