Кастомные методы

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

Принципы расширения объектов ScrollMagic

ScrollMagic построен на прототипной модели JavaScript, что позволяет расширять его классы:

  • ScrollMagic.Controller
  • ScrollMagic.Scene

Добавление методов возможно через прототип:

ScrollMagic.Scene.prototype.myCustomMethod = function() {
    // логика
    return this;
};

Ключевой момент — сохранение цепочки вызовов (return this), чтобы не нарушить fluent API.

Добавление кастомных методов для Scene

Пример: метод для логирования состояния сцены

ScrollMagic.Scene.prototype.logState = function() {
    this.on("enter leave", function(event) {
        console.log("Scene state:", event.type);
    });
    return this;
};

Использование:

new ScrollMagic.Scene({
    triggerElement: "#trigger"
})
.logState()
.addTo(controller);

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

  • Используется событие enter и leave
  • Метод инкапсулирует повторяющуюся логику
  • Повышается читаемость кода

Кастомизация поведения через переопределение методов

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

Пример: расширение метода addIndicators

const originalAddIndicators = ScrollMagic.Scene.prototype.addIndicators;

ScrollMagic.Scene.prototype.addIndicators = function(options) {
    console.log("Добавление индикаторов");
    return originalAddIndicators.call(this, options);
};

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

  • Сохраняется оригинальная реализация
  • Добавляется дополнительная логика
  • Используется call для передачи контекста

Создание вспомогательных методов для анимаций

Пример: метод для плавного появления элемента

ScrollMagic.Scene.prototype.fadeIn = function(duration = 0.5) {
    this.on("enter", function() {
        TweenMax.to(this.triggerElement(), duration, { opacity: 1 });
    });
    return this;
};

Преимущества:

  • Упрощение повторяющихся анимаций
  • Централизация логики
  • Возможность параметризации

Расширение Controller

Контроллер управляет сценами, и его расширение позволяет централизовать поведение.

Пример: метод для удаления всех сцен

ScrollMagic.Controller.prototype.removeAllScenes = function() {
    this.info("scenes").forEach(scene => scene.destroy(true));
};

Использование:

controller.removeAllScenes();

Инкапсуляция сложной логики

Пример: метод для синхронизации нескольких сцен

ScrollMagic.Controller.prototype.syncScenes = function(scenes) {
    scenes.forEach(scene => {
        scene.on("progress", function(event) {
            scenes.forEach(otherScene => {
                if (otherScene !== scene) {
                    otherScene.progress(event.progress);
                }
            });
        });
    });
};

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

  • Управление группой сцен
  • Синхронизация состояния
  • Повышение гибкости интерфейса

Создание плагинов на основе кастомных методов

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

Структура простого плагина

(function() {
    ScrollMagic.Scene.prototype.highlight = function(className = "active") {
        this.on("enter", function() {
            this.triggerElement().classList.add(className);
        });
        this.on("leave", function() {
            this.triggerElement().classList.remove(className);
        });
        return this;
    };
})();

Преимущества:

  • Изолированность
  • Повторное использование
  • Простота подключения

Работа с цепочками методов

ScrollMagic активно использует chaining:

scene
    .setPin("#element")
    .setTween(tween)
    .addIndicators();

Кастомные методы должны поддерживать эту концепцию:

ScrollMagic.Scene.prototype.custom = function() {
    // логика
    return this;
};

Если метод возвращает не this, цепочка разрывается.

Управление состоянием внутри кастомных методов

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

ScrollMagic.Scene.prototype.setData = function(key, value) {
    if (!this._customData) {
        this._customData = {};
    }
    this._customData[key] = value;
    return this;
};

ScrollMagic.Scene.prototype.getData = function(key) {
    return this._customData ? this._customData[key] : undefined;
};

Использование:

scene.setData("visited", true);
console.log(scene.getData("visited"));

Обработка событий внутри кастомных методов

ScrollMagic использует событийную модель:

  • enter
  • leave
  • progress
  • start
  • end

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

ScrollMagic.Scene.prototype.onProgress Log = function() {
    this.on("progress", function(event) {
        console.log("Progress:", event.progress);
    });
    return this;
};

Комбинирование методов

Кастомные методы могут вызывать другие методы:

ScrollMagic.Scene.prototype.fadeInWithLog = function() {
    return this
        .fadeIn()
        .logState();
};

Преимущества:

  • Повторное использование
  • Минимизация дублирования
  • Улучшение читаемости

Производительность и оптимизация

При создании кастомных методов важно учитывать:

  • Избегание лишних обработчиков событий
  • Удаление сцен при необходимости (destroy)
  • Минимизация DOM-операций
  • Кэширование элементов

Пример оптимизации

ScrollMagic.Scene.prototype.cacheElement = function() {
    this._el = this.triggerElement();
    return this;
};

Ошибки и подводные камни

1. Потеря контекста

this.triggerElement // функция
this.triggerElement() // правильный вызов

2. Нарушение цепочки

return; // ошибка
return this; // правильно

3. Повторное навешивание событий

this.on("enter", handler); // при каждом вызове метода добавляется новый обработчик

Решение — проверка:

if (!this._hasHandler) {
    this.on("enter", handler);
    this._hasHandler = true;
}

Организация кода

Рекомендуется выносить кастомные методы в отдельные файлы:

/scrollmagic/
    custom/
        scene.extensions.js
        controller.extensions.js

Подключение:

<script src="scrollmagic.min.js"></script>
<script src="scene.extensions.js"></script>

Тестирование кастомных методов

Проверяются:

  • корректность chaining
  • отсутствие утечек памяти
  • правильная работа событий
  • совместимость с другими методами

Пример:

const scene = new ScrollMagic.Scene();

console.assert(scene.custom() === scene, "Метод должен возвращать this");

Практическое применение

Кастомные методы особенно полезны в следующих сценариях:

  • сложные анимационные последовательности
  • единый стиль взаимодействия
  • повторяющиеся UI-паттерны
  • интеграция с внешними библиотеками (GSAP, Three.js)

Архитектурный подход

При масштабировании проекта:

  • создаются наборы методов (modules)
  • используется единый namespace
  • документируются интерфейсы методов

Пример:

ScrollMagic.Scene.prototype.ui = {};
ScrollMagic.Scene.prototype.ui.fadeIn = function() {
    // ...
};

Расширение через классы-обертки

Альтернатива прототипам — создание оберток:

class CustomScene {
    constructor(scene) {
        this.scene = scene;
    }

    fadeIn() {
        this.scene.on("enter", () => {
            // ...
        });
        return this;
    }
}

Преимущества:

  • изоляция логики
  • отсутствие вмешательства в оригинальный API
  • удобство тестирования

Итоговая роль кастомных методов

Кастомные методы превращают ScrollMagic из библиотеки в полноценный инструмент разработки, позволяя:

  • стандартизировать поведение
  • ускорять разработку
  • снижать сложность кода
  • создавать собственные абстракции над прокруткой
Оглавление