Частые ошибки при инициализации

Неправильная структура DOM

Locomotive Scroll требует специфической структуры DOM для корректной работы. Ошибки на этом этапе часто приводят к отсутствию плавного скролла или некорректной анимации элементов.

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

  • Контейнер с атрибутом data-scroll-container должен быть единственным и содержать все элементы, которые участвуют в прокрутке.
  • Элементы, имеющие атрибут data-scroll, должны находиться внутри контейнера.
  • Использование нескольких контейнеров с data-scroll-container без отдельной инициализации для каждого вызовет конфликты.

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

<div data-scroll-container>
    <section data-scroll data-scroll-speed="1">Секция 1</section>
    <section data-scroll data-scroll-speed="2">Секция 2</section>
</div>

Несоответствие CSS и JavaScript

Locomotive Scroll требует, чтобы контейнер имел правильные CSS-свойства. Наиболее частые ошибки:

  • Отсутствие height: 100% или overflow: hidden на родительском контейнере.
  • Использование position: fixed на контейнере или элементах, которые должны анимироваться.
  • Конфликт transform свойств на контейнере, особенно если используется другой скрипт параллакса.

Правильные настройки CSS:

html, body {
    height: 100%;
    overflow: hidden;
}

[data-scroll-container] {
    position: relative;
}

Инициализация до загрузки DOM

Ошибка заключается в том, что new LocomotiveScroll() вызывается до того, как DOM полностью сформирован. В результате скрипт не находит контейнер и элементы для скролла.

Правильный подход:

document.addEventListener("DOMContentLoaded", () => {
    const scroll = new LocomotiveScroll({
        el: document.querySelector('[data-scroll-container]'),
        smooth: true
    });
});

Игнорирование обновления после динамического контента

Если элементы добавляются в DOM после инициализации, Locomotive Scroll не будет их учитывать, что проявляется в зависании скролла или неправильной позиции элементов.

Решение: вызвать метод update() после изменения DOM.

scroll.update();

Конфликт с другими библиотеками скролла

Частая ошибка — одновременное использование нескольких скриптов, управляющих прокруткой (например, GSAP ScrollTrigger с scrollerProxy) без правильной интеграции. Это вызывает дёргание и разрыв анимаций.

Совет: всегда проверять совместимость и использовать методы интеграции, предоставленные документацией.

Неправильные параметры инициализации

  • smooth: true включается только для вертикального скролла. Для горизонтального требуется дополнительная настройка.
  • getDirection и getSpeed не работают без активации smooth.
  • Указание неверного селектора в el приводит к silent failure — скролл не инициализируется, и ошибок в консоли может не быть.

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

  • Автоматическое отключение скролла на мобильных устройствах (mobile: { smooth: false }) без корректной проверки может сломать анимации.
  • Использование overflow: hidden на body приводит к невозможности взаимодействия с нативным скроллом.

Ошибки при использовании с SPA (Single Page Application)

При навигации между страницами:

  • Не уничтожается предыдущий экземпляр Locomotive Scroll (scroll.destroy()), что приводит к накоплению обработчиков и падению производительности.
  • Не обновляются размеры контейнера и элементы после смены контента.

Пример правильного управления экземпляром:

if (scroll) scroll.destroy();
scroll = new LocomotiveScroll({
    el: document.querySelector('[data-scroll-container]'),
    smooth: true
});

Игнорирование перерисовки при изменении размеров окна

Locomotive Scroll не реагирует автоматически на изменение размеров окна, если оно было вызвано динамическими изменениями DOM. Это приводит к рассинхронизации скролла.

Решение:

window.addEventListener('resize', () => {
    scroll.update();
});

Итоговое правило

Все ошибки при инициализации Locomotive Scroll сводятся к трём главным принципам:

  1. Строгая структура DOM — правильные контейнеры и элементы с нужными атрибутами.
  2. Корректные CSS-свойства — отсутствие конфликтов с позиционированием и overflow.
  3. Управление жизненным циклом экземпляра — инициализация после DOM, обновление при динамических изменениях, уничтожение перед повторной инициализацией.

Соблюдение этих правил минимизирует большинство проблем и обеспечивает стабильную работу библиотеки на любых проектах.

Оглавление