Breaking changes

Locomotive Scroll активно развивается, и с каждой новой версией появляются изменения, которые могут нарушить работу существующего кода. Раздел breaking changes особенно важен при обновлении библиотеки, так как позволяет заранее подготовить проект к новым требованиям и избежать неожиданных ошибок.

1. Удаление и переименование опций

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

  • el Ранее основной контейнер для скролла задавался через el: document.querySelector('#scroll'). Сейчас поддерживается только прямое DOM-узловое значение, без возможности передавать селектор в виде строки. Передача строки вызовет ошибку.

  • smoothMobile Параметр, отвечавший за плавность скролла на мобильных устройствах, был удалён. Все мобильные устройства теперь используют плавный скролл автоматически или полное отключение через smooth: false.

  • getDirection и getSpeed Методы, возвращавшие направление и скорость прокрутки, переехали из публичного API в приватный внутренний функционал. Использование scroll.getDirection() или scroll.getSpeed() больше не поддерживается и приведёт к ошибке.

2. Изменения в событиях

Locomotive Scroll активно использует события для отслеживания прокрутки. В новых версиях произошли следующие изменения:

  • Событие call Ранее call срабатывал на каждом кадре для элементов с data-scroll-call. Сейчас оно срабатывает только при входе элемента в видимую область и при выходе из неё. Для старой логики придётся использовать кастомные события через Intersection Observer.

  • Удаление события scroll на инстансе В старых версиях можно было подписываться на событие:

    scroll.on('scroll', (obj) => console.log(obj.scroll.y));

    Теперь событие scroll больше не существует. Для получения текущей позиции прокрутки нужно использовать scroll.scroll.instance.scroll.y в комбинации с requestAnimationFrame.

3. Изменения в API методов

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

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

    scroll.destroy();
scroll = new LocomotiveScroll({ el: container, smooth: true });

  • destroy() Метод полностью очищает все обработчики событий и сбрасывает стили. В старых версиях destroy() оставлял контейнер с позиционированием fixed; теперь все стили сбрасываются корректно, что может повлиять на кастомные анимации.

  • start() и stop() Эти методы больше не контролируют плавность скролла. Их использование теперь ограничено внутренними оптимизациями, а для приостановки скролла необходимо использовать:

    scroll.stop(); // Приостанавливает скролл
scroll.start(); // Возобновляет скролл

    Но важно учитывать, что все кастомные анимации должны быть синхронизированы вручную.

4. Работа с прокруткой на мобильных устройствах

  • mobile и tablet опции Параметры конфигурации mobile: { breakpoint, smooth } и tablet: { breakpoint, smooth } были заменены на единый параметр smartphone и tablet. Старый формат больше не поддерживается и вызовет ошибку при инициализации.

  • Изменение поведения touch-событий Прокрутка теперь использует passive listeners по умолчанию, что улучшает производительность, но может нарушить логику кастомных обработчиков touchstart/touchmove. Для совместимости требуется вручную отменять passive:

    document.addEventListener('touchmove', handler, { passive: false });

5. Анимации и data-атрибуты

  • data-scroll-speed и data-scroll-delay Поведение этих атрибутов изменилось: скорость теперь считается относительно текущего контейнера с учетом его позиции, а не глобального документа. При обновлении проекта старые анимации могут выглядеть иначе.

  • data-scroll-repeat Атрибут повторного триггера больше не работает для элементов, полностью ушедших из зоны видимости. Элементы повторно активируются только при частичном пересечении с viewport.

6. CSS и стили

  • Сброс transform В новых версиях Locomotive Scroll управляет transform: translate3d() для контейнера и элементов с data-scroll. Старые кастомные трансформации могут конфликтовать. Для корректной работы необходимо использовать will-change: transform и избегать конфликтов с inline-стилями.

  • Позиционирование fixed Элементы с position: fixed внутри контейнера теперь работают корректно относительно контейнера, а не документа. Старые трюки с fixed могут требовать переработки CSS.

7. Рекомендации по обновлению

  • Проверять все инициализации и заменить селекторы на прямые DOM-узлы.
  • Заменить удалённые методы и события на новые подходы с requestAnimationFrame и Intersection Observer.
  • Пересмотреть мобильные и планшетные настройки в соответствии с новой конфигурацией.
  • Тщательно протестировать все анимации с data-атрибутами и фиксированными элементами.

Эти изменения являются ключевыми для понимания, как адаптировать старый проект под новые версии Locomotive Scroll, избегая ошибок, конфликтов и неожиданных визуальных багов.

Оглавление