API расширений

ScrollMagic предоставляет мощный инструмент для управления анимацией и поведением элементов на странице в зависимости от прокрутки. API расширений библиотеки позволяет создавать кастомные эффекты, интегрировать сторонние анимационные библиотеки и управлять сценами с высокой точностью. В основе работы лежат сцены (Scenes) и контроллеры (Controller), расширяемые через плагины и собственные методы.

Подключение и инициализация расширений

Расширения ScrollMagic чаще всего реализуются через подключение дополнительных скриптов поверх базовой библиотеки. Например, для интеграции с GSAP используется animation.gsap.js, для управления классами — debug.addIndicators.js.

Пример подключения:

Создание контроллера:

var controller = new ScrollMagic.Controller();

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

Расширения через методы сцены

Сцена в ScrollMagic имеет стандартный набор методов: duration(), offset(), triggerElement(), setTween(), setClassToggle(). Расширения позволяют добавлять кастомное поведение через:

  • Custom events – пользовательские события сцены.
  • Callbacks – функции обратного вызова на ключевые моменты.
  • Plugins – подключаемые библиотеки анимации или визуальные индикаторы.

Пример добавления пользовательского события:

var scene = new ScrollMagic.Scene({
    triggerElement: "#section1",
    duration: 300
})
.on("enter leave", function(e) {
    console.log("Событие:", e.type);
})
.addTo(controller);

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

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

ScrollMagic не ограничивается внутренними методами анимации. Расширение animation.gsap позволяет синхронизировать сцены с Timeline и Tween объекта GSAP:

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

var scene = new ScrollMagic.Scene({
    triggerElement: "#trigger",
    duration: 500
})
.setTween(tween)
.addIndicators()
.addTo(controller);

Особенности работы:

  • setTween() принимает как отдельный Tween, так и Timeline, что позволяет строить сложные последовательные анимации.
  • Параметр duration сцены определяет, на каком отрезке прокрутки будет выполняться анимация.
  • Интеграция с GSAP позволяет плавно синхронизировать движение элементов с прокруткой страницы.

Кастомные индикаторы и отладка

Расширение debug.addIndicators используется для визуализации триггеров и зон действия сцен. Методы индикаторов поддерживают кастомизацию:

scene.addIndicators({
    name: "Scene 1",
    colorStart: "#FF0000",
    colorEnd: "#00FF00",
    indent: 20
});

Параметры:

  • name – отображаемое название сцены.
  • colorStart и colorEnd – цвета начала и конца зоны действия.
  • indent – отступ индикатора от края страницы.

Индикаторы не влияют на производительность анимации и служат исключительно для отладки и точного позиционирования сцен.

Создание собственных расширений

ScrollMagic предоставляет возможность создавать полностью кастомные расширения через прототип сцены:

ScrollMagic.Scene.prototype.addCustomEffect = function(options) {
    this.on("progress", function(event) {
        var progress = event.progress;
        options.target.style.opacity = progress;
    });
    return this;
};

var scene = new ScrollMagic.Scene({triggerElement: "#section2", duration: 400})
    .addCustomEffect({target: document.getElementById("fadeBox")})
    .addTo(controller);

Принципы:

  • Расширение возвращает this для цепочки вызовов (chaining).
  • Использование события progress позволяет отслеживать состояние анимации относительно прокрутки.
  • Кастомные методы легко интегрируются с существующими сценами и другими расширениями.

Управление динамическими сценами

Расширения также позволяют создавать сцены на лету, управлять их количеством и удалять их без утечек памяти:

function createScene(id, duration) {
    var scene = new ScrollMagic.Scene({
        triggerElement: id,
        duration: duration
    })
    .setClassToggle(id, "active")
    .addTo(controller);

    return scene;
}

var scenes = [];
["#sec1", "#sec2", "#sec3"].forEach((el) => {
    scenes.push(createScene(el, 300));
});

// удаление сцены
scenes[0].destroy(true);

Особенности:

  • destroy(true) удаляет сцену полностью и очищает все обработчики.
  • Управление коллекцией сцен позволяет создавать интерактивные интерфейсы с динамическими элементами.

Работа с несколькими контроллерами

Иногда требуется независимое управление прокруткой разных блоков. ScrollMagic поддерживает несколько контроллеров:

var controller1 = new ScrollMagic.Controller({vertical: true});
var controller2 = new ScrollMagic.Controller({vertical: false});

var scene1 = new ScrollMagic.Scene({triggerElement: "#vert"})
    .setClassToggle("#vert", "active")
    .addTo(controller1);

var scene2 = new ScrollMagic.Scene({triggerElement: "#hor"})
    .setTween("#hor", {x: 300})
    .addTo(controller2);

Особенности:

  • Каждый контроллер отслеживает сцены независимо.
  • Контроллер может быть настроен для горизонтальной или вертикальной прокрутки.
  • Использование нескольких контроллеров удобно при создании сложных интерфейсов с разными направлениями анимаций.

Использование событий расширений

API расширений предоставляет ряд событий, полезных для сложных сценариев:

  • enter – элемент входит в зону действия.
  • leave – элемент покидает зону действия.
  • start / end – сцена достигла начала или конца.
  • progress – изменение прогресса в диапазоне 0–1.

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

scene.on("enter leave progress", function(event) {
    if(event.type === "progress") {
        console.log("Прогресс:", event.progress);
    } else {
        console.log("Событие:", event.type);
    }
});

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

Оглавление