Тестирование на устройствах

Для начала работы с Shepherd.js необходимо подключить саму библиотеку и её зависимости. В современном JavaScript-проекте это делается через npm или yarn:

npm install shepherd.js

или

yarn add shepherd.js

После установки импортируется основной класс и стили:

import Shepherd from 'shepherd.js';
import 'shepherd.js/dist/css/shepherd.css';

Shepherd.js использует Popper.js для позиционирования подсказок, поэтому убедитесь, что зависимости установлены автоматически через пакет. Для управления стилями рекомендуется кастомизировать CSS через собственные классы или использовать встроенные темы.

Создание тура и шагов

Основная единица работы — это тур (Shepherd.Tour). Тур состоит из последовательности шагов (step), каждый из которых содержит информацию о контенте, привязке к элементу DOM и поведении.

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

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в наше приложение.',
  attachTo: {
    element: '.header-logo',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

tour.addStep({
  id: 'menu',
  text: 'Здесь находится главное меню.',
  attachTo: {
    element: '.main-menu',
    on: 'right'
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Закончить',
      action: tour.complete
    }
  ]
});

tour.start();

Ключевые моменты:

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

Тестирование тура на разных устройствах

Эмуляция экранов и разрешений

Для проверки адаптивности рекомендуется использовать инструменты браузера (DevTools) с эмуляцией мобильных устройств. Shepherd.js автоматически позиционирует подсказки относительно указанных элементов, но на малых экранах могут возникать сбои в видимости или перекрытия.

Примеры проблем:

  • Элемент, к которому привязан шаг, скрыт за модальным окном.
  • Подсказка выходит за границы экрана.
  • Прокрутка страницы работает некорректно из-за scrollTo: true.

Для корректного тестирования следует:

  1. Использовать разные разрешения (320px, 375px, 768px, 1024px).
  2. Проверять позиционирование всех шагов.
  3. Следить, чтобы кнопки навигации оставались доступными.

Работа с сенсорными экранами

На мобильных устройствах с сенсорным вводом важно учитывать:

  • Тап-зоны кнопок должны быть достаточными для пальцев.
  • Использование preventScroll может влиять на поведение скролла.
  • События click заменяются на touchstart автоматически, но иногда требуется ручная обработка.

Рекомендуется комбинировать responsive CSS и проверку на физическом устройстве, так как эмуляторы не всегда воспроизводят поведение жестов.

Асинхронные шаги и динамический контент

Если элементы DOM загружаются динамически, шаги нужно создавать после появления элементов. Shepherd.js предоставляет метод when() для отслеживания событий тура:

tour.addStep({
  id: 'dynamic-step',
  text: 'Это динамически созданный элемент.',
  attachTo: {
    element: '#dynamic-element',
    on: 'top'
  },
  buttons: [
    { text: 'Далее', action: tour.next }
  ]
});

document.addEventListener('DOMContentLoaded', () => {
  const dynamicElement = document.createElement('div');
  dynamicElement.id = 'dynamic-element';
  document.body.appendChild(dynamicElement);
});

Проверка на устройствах: обязательно убедиться, что шаг появляется корректно даже при асинхронной подгрузке контента.

Управление событиями тура

Shepherd.js поддерживает события на уровне тура и шагов. Для тестирования удобно отслеживать:

tour.on('start', () => console.log('Тур запущен'));
tour.on('complete', () => console.log('Тур завершён'));
tour.on('cancel', () => console.log('Тур отменён'));

События помогают:

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

Тонкости адаптивного позиционирования

  • attachTo.on поддерживает значения: top, bottom, left, right, а также auto — Shepherd выбирает оптимальное положение.
  • Для маленьких экранов иногда рекомендуется использовать modalOverlay: true, чтобы фокусировать пользователя на подсказке и избегать перекрытий.
  • Если шаг выходит за границы экрана, Popper.js автоматически пытается скорректировать позицию, но это не всегда идеально. Можно использовать опцию popperOptions для точной настройки поведения:
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    popperOptions: {
      modifiers: [{ name: 'preventOverflow', options: { padding: 10 } }]
    }
  }
});

Практические рекомендации по тестированию

  1. Проверять тур на минимальной ширине экрана, на планшетах и десктопах.
  2. Проверять шаги с динамическим контентом и модальными окнами.
  3. Следить за видимостью всех кнопок навигации.
  4. Использовать события show и hide для логирования проблемных шагов.
  5. Настраивать scrollTo и popperOptions для корректного позиционирования на небольших экранах.
  6. Тестировать физически на устройствах с разными ОС и браузерами, поскольку эмуляторы не всегда корректно имитируют поведение скролла и сенсорных жестов.

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

Оглавление