Переход с предыдущих версий

ScrollMagic — это библиотека для управления анимациями при прокрутке страницы. С течением времени она эволюционировала, и переход с более старых версий на актуальные версии требует понимания изменений в API, логике сцены и настройках контроллера.

Контроллеры

В ранних версиях ScrollMagic контроллер создавался с минимальными параметрами:

var controller = new ScrollMagic.Controller();

В последних версиях добавлены расширенные опции:

  • container – DOM-элемент, к которому привязывается прокрутка. Ранее всегда использовался window.
  • vertical – логическая вертикальная или горизонтальная прокрутка (true по умолчанию для вертикальной).
  • globalSceneOptions – объект с настройками, которые применяются ко всем сценам контроллера, что упрощает код и уменьшает дублирование.

Пример:

var controller = new ScrollMagic.Controller({
  container: "#scrollContainer",
  vertical: true,
  globalSceneOptions: { triggerHook: 0.5 }
});

Использование globalSceneOptions является основной оптимизацией при переходе с предыдущих версий, где каждая сцена требовала отдельного указания triggerHook, duration и т.д.

Сцены

Основной строительный блок ScrollMagic — это сцена (ScrollMagic.Scene). В ранних версиях сцена создавалась примерно так:

var scene = new ScrollMagic.Scene({ 
  triggerElement: "#element", 
  duration: 200 
})
.setPin("#element")
.addTo(controller);

В новых версиях изменился механизм событий и методов:

  • on() – стандарт для привязки событий сцены (enter, leave, progress, start, end).
  • off() – для удаления слушателей.
  • setTween() – теперь поддерживает любые библиотеки анимации, включая GSAP 3.
  • addIndicators() – инструмент для отладки, ранее был доступен через плагин, теперь интегрирован в основной код (если подключен).

Пример современной сцены с Tween анимацией:

var tween = gsap.to("#element", { x: 300, rotation: 360, duration: 2 });

var scene = new ScrollMagic.Scene({
  triggerElement: "#trigger",
  duration: 400,
  triggerHook: 0.25
})
.setTween(tween)
.addIndicators({ name: "Slide Animation" })
.addTo(controller);

Ключевые отличия от старых версий:

  1. События сцены: ранние версии использовали .on("start end progress"), теперь рекомендуется точное указание событий.
  2. Пинning элементов: метод setPin() остался, но теперь корректно работает с Flexbox и Grid макетами, чего не было в старых версиях.
  3. Tween-анимации: поддержка GSAP 3 и современных CSS-анимаций через setTween().

Триггерные элементы и hook’и

В старых версиях triggerHook принимал строковые значения ("onEnter", "onCenter", "onLeave"). В новых версиях предпочтительно использование чисел от 0 до 1:

  • 0 — верхняя граница контейнера.
  • 0.5 — центр контейнера.
  • 1 — нижняя граница.

Это позволяет точно позиционировать момент запуска анимации.

var scene = new ScrollMagic.Scene({
  triggerElement: "#element",
  triggerHook: 0.75
});

Также изменилось поведение offset: в новых версиях оно рассчитывается относительно текущего triggerHook, а не от начала документа, что улучшает совместимость с динамическими элементами.

Работа с динамическим контентом

Ранее ScrollMagic плохо справлялся с динамически добавляемыми элементами. Теперь можно использовать метод refresh() контроллера после изменения DOM:

controller.update(true);
controller.refresh();

Это обновляет позиции триггеров и высоты сцен без необходимости пересоздавать все сцены заново.

Поддержка модульной структуры

Современные версии ScrollMagic поддерживают ES-модули и import/export:

import ScrollMagic from 'scrollmagic';
import 'scrollmagic/scrollmagic/uncompressed/plugins/animation.gsap';
import 'scrollmagic/scrollmagic/uncompressed/plugins/debug.addIndicators';

Это особенно важно для проектов на Webpack или Vite, где подключение глобальных скриптов через <script> становится нежелательным.

Итоговые рекомендации при переходе

  • Использовать globalSceneOptions для уменьшения повторений.
  • Перевести все события на современный формат on("enter"), on("leave").
  • Проверить работу triggerHook и offset в числовых значениях.
  • Обновить анимации на GSAP 3 через setTween().
  • После динамических изменений DOM вызывать controller.update() и controller.refresh().
  • При модульной сборке подключать ScrollMagic через ES6 import и подключать необходимые плагины явно.

Эти изменения позволяют не только сохранить совместимость с существующим кодом, но и использовать новые возможности ScrollMagic для более точного и производительного управления анимациями при прокрутке.

Оглавление