Решение проблем при миграции

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

Типичные симптомы:

  • Скроллинг перестал работать или работает частично.
  • Навигационные точки (dots) отображаются неправильно.
  • Обработчики событий, такие как afterLoad или onLeave, не вызываются.

Обновление структуры HTML

fullPage.js версии 4 и выше требует строгой структуры блоков:

<div id="fullpage">
  <div class="section">Секция 1</div>
  <div class="section">Секция 2</div>
  <div class="section">Секция 3</div>
</div>

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

  • Контейнер должен иметь уникальный id или class.
  • Каждая секция оборачивается в блок с классом section.
  • Для вертикальных слайдов внутри секции используется класс slide.

Ошибки при миграции часто связаны с отсутствием этих классов или изменением структуры DOM, из-за чего fullPage.js не может корректно вычислить высоту и положение секций.

Актуализация параметров и методов

Многие опции старых версий были удалены или заменены:

Старый параметр Новый эквивалент Примечание
anchors anchors Остался, но синтаксис вызова обработчиков изменился
css3 убран, fullPage.js всегда использует CSS3 при возможности Не нужно указывать
scrollingSpeed scrollingSpeed Значение в миллисекундах
fitToSection fitToSection Можно отключить для кастомного скроллинга

Методы:

  • Старый метод moveSectionDown() сохраняется, но теперь рекомендуется использовать fullpage_api.moveSectionDown().
  • Обработчики событий подключаются через fullpage_api.setAllowScrolling(false) и события afterLoad, onLeave через объект конфигурации при инициализации.

Проблемы с кастомными обработчиками событий

Если при миграции перестали работать функции типа onLeave:

new fullpage('#fullpage', {
  onLeave: function(origin, destination, direction){
    console.log(origin.index, destination.index);
  }
});
  • Проверить, что объект origin корректно передаётся.
  • В версии 4+ объект содержит index, anchor, item, а не просто число.
  • Для динамически добавляемых секций обработчики нужно инициализировать после добавления DOM.

Работа с адаптивной версткой

Ранее часто использовался параметр responsiveWidth или responsiveHeight. В новых версиях рекомендуется:

  • Использовать responsiveSlides для слайдов внутри секции.
  • Управлять видимостью блоков через CSS с медиа-запросами, оставляя полную структуру fullPage.js неизменной.

Интеграция с другими библиотеками

При использовании анимаций (GSAP, Anime.js) или параллакса:

  • Проверить, что методы анимации вызываются после инициализации fullPage.js (afterRender).
  • Для плавного взаимодействия со скроллингом использовать fullpage_api.setAllowScrolling(false) перед запуском кастомной анимации и включать обратно после завершения.

Отладка и логирование

  • Проверить консоль на ошибки, связанные с fullpage_api или DOM.
  • Для секций, которые не скроллятся, убедиться, что их высота больше 0 и они правильно вложены.
  • Использовать fullpage_api.getActiveSection() для контроля текущей секции во время миграции и отладки.

Совместимость с мобильными устройствами

В новых версиях:

  • Скроллинг на мобильных устройствах по умолчанию включен через touchSensitivity.
  • Для отключения свайпа и сохранения кастомного поведения используется fullpage_api.setAllowScrolling(false, 'touch').
  • Проверить работу на iOS, Android и планшетах, так как баги часто проявляются только на тач-устройствах.

Автоматическая миграция старого кода

Полезная стратегия:

  1. Переписать инициализацию через объект конфигурации new fullpage('#fullpage', {...}).
  2. Заменить все обращения к старым методам на fullpage_api.
  3. Проверить работу каждой секции и слайдов отдельно.
  4. Использовать консоль для логирования событий afterLoad и onLeave, чтобы убедиться, что обработчики вызываются корректно.

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

Оглавление