Изменения в API

Библиотека ScrollMagic с момента своего появления прошла через несколько версий, каждая из которых привносила значительные изменения в API. Понимание этих изменений критически важно для корректного использования библиотеки и миграции старого кода на новые версии.

1. Создание сцены (Scene)

Ранее: сцены создавались через прямой конструктор new ScrollMagic.Scene({ options }), где опции включали duration, offset, triggerElement и triggerHook.

Теперь: подход к опциям стал более гибким, появились дополнительные параметры:

  • reverse — управляет возможностью обратного проигрывания анимации при скролле назад.
  • loglevel — задает уровень логирования событий сцены для отладки.
  • tweenChanges — определяет, обновлять ли анимацию плавно при изменении прогресса сцены.
const scene = new ScrollMagic.Scene({
    triggerElement: "#trigger",
    duration: 300,
    triggerHook: 0.5,
    reverse: true,
    tweenChanges: true
});

2. Добавление анимации через Tween

ScrollMagic не содержит встроенной анимации, но интегрируется с популярными библиотеками, такими как GSAP.

Изменения:

  • Метод .setTween() теперь принимает как одиночный tween, так и массив tween-объектов для последовательного запуска.
  • Появилась возможность передавать функцию вместо объекта, что позволяет динамически создавать анимацию в зависимости от состояния страницы.
scene.setTween(TweenMax.to("#animate", 1, {x: 100}));

или с динамическим созданием:

scene.setTween(() => TweenMax.to("#animate", 1, {y: Math.random() * 500}));

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

События: start, end, enter, leave, progress API событий стало более последовательным:

  • .on(event, callback) — теперь поддерживает цепочку вызовов, возвращая сам объект сцены.
  • .off(event, callback) — удаление конкретного обработчика событий.
  • .trigger(event) — ручной вызов события для тестирования и отладки.
scene
    .on("enter leave", function (event) {
        console.log(event.type, event.scrollDirection);
    })
    .on("progress", function (event) {
        console.log("Progress:", event.progress);
    });

4. Pinning элементов

Функционал закрепления элементов (.setPin()) стал более гибким:

  • Появилась опция pushFollowers, управляющая поведением последующих элементов при закреплении.
  • Опция spacerClass позволяет задавать пользовательский класс для временного контейнера, создаваемого ScrollMagic.
  • Поддержка динамического изменения высоты сцены при изменении контента.
scene.setPin("#pinned", {pushFollowers: false, spacerClass: "custom-spacer"});

5. Контроллер (Controller)

Контроллер теперь выполняет больше функций по управлению сценами:

  • addScene(scene) / removeScene(scene) — добавление и удаление сцены из контроллера.
  • update() — обновление состояния всех сцен при изменении DOM или размеров окна.
  • enabled(boolean) — включение или отключение контроллера без удаления сцен.
  • scrollTo(target, [options]) — плавный скролл к определенному элементу, заменивший собственные сторонние плагины.
const controller = new ScrollMagic.Controller({vertical: true, globalSceneOptions: {triggerHook: 0.5}});
controller.addScene(scene);
controller.scrollTo("#target");

6. Глобальные изменения API

  • Использование globalSceneOptions: позволяет задать опции, которые будут применяться ко всем сценам контроллера.
  • Удаление устаревших методов: старые методы вроде addIndicators() для дебага теперь доступны только через отдельный плагин.
  • Упрощение цепочек вызовов: большинство методов возвращают объект сцены или контроллера, что позволяет писать компактный и читаемый код.
const controller = new ScrollMagic.Controller({
    globalSceneOptions: {triggerHook: 0.2, reverse: false}
});

new ScrollMagic.Scene({triggerElement: "#section"})
    .setTween("#animate", {x: 200})
    .addTo(controller);

7. Адаптация к мобильным устройствам

  • Поддержка сенсорного скролла и оптимизация производительности при прокрутке с тач-устройств.
  • Новые события resize и refresh помогают динамически обновлять сцены при изменении размеров окна.
controller.on("resize", () => {
    controller.update(true);
});

8. Интеграция с современными фреймворками

ScrollMagic теперь проще интегрировать с React, Vue и Angular через использование ref и прямое добавление сцены к элементу:

// React пример
useEffect(() => {
    const scene = new ScrollMagic.Scene({triggerElement: ref.current})
        .setTween("#animate", {opacity: 1, y: 0})
        .addTo(controller);
    return () => scene.destroy(true);
}, []);

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

Оглавление