TypeScript: типизация GSAP

GSAP (GreenSock Animation Platform) предоставляет мощный набор инструментов для анимации в JavaScript. При использовании TypeScript важно правильно типизировать объекты и функции GSAP, чтобы обеспечить автодополнение, предотвращение ошибок на этапе компиляции и повышенную читаемость кода.

Импорт GSAP и типов

Для корректной работы с TypeScript необходимо импортировать GSAP и соответствующие типы. Основной пакет предоставляет типы для gsap.to, gsap.from, gsap.fromTo и других методов:

import gsap, { TweenTarget, TweenVars, TimelineVars } from "gsap";
  • TweenTarget — определяет допустимые объекты анимации (DOM-элементы, строки-селекторы, массивы элементов).
  • TweenVars — интерфейс для описания параметров анимации (duration, x, opacity, ease и т. д.).
  • TimelineVars — параметры для настройки таймлайнов (repeat, yoyo, defaults).

Типизация целей анимации

Цели анимации могут быть следующими:

const element: HTMLElement = document.querySelector("#box")!;
const elements: NodeListOf<HTMLElement> = document.querySelectorAll(".boxes");

Тип TweenTarget допускает:

  • Один элемент HTMLElement
  • Массив элементов HTMLElement[]
  • NodeList NodeListOf<HTMLElement>
  • Строковый селектор string

Пример типизированного твина:

gsap.to(element, { x: 100, opacity: 0.5, duration: 1 });

TypeScript проверяет, что element соответствует допустимому TweenTarget, а x, opacity и duration — корректны по типу.

Типизация параметров анимации

Интерфейс TweenVars позволяет строго типизировать параметры анимации:

const tweenParams: TweenVars = {
    x: 200,
    y: 50,
    rotation: 45,
    duration: 2,
    ease: "power2.inOut"
};
gsap.to(element, tweenParams);

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

  • Автодополнение всех свойств GSAP
  • Проверка типов чисел, строк и специальных значений (например, ease принимает только допустимые строки)
  • Уменьшение ошибок при работе с комплексными анимациями

Таймлайны и типизация

gsap.timeline() позволяет объединять последовательные и параллельные анимации. Таймлайны могут быть типизированы через TimelineVars:

const tlParams: TimelineVars = {
    defaults: { duration: 1, ease: "power1.out" },
    repeat: 2,
    yoyo: true
};

const timeline = gsap.timeline(tlParams);

timeline.to(element, { x: 100 })
        .to(element, { y: 50, rotation: 90 });

В defaults можно указать типизированные параметры TweenVars, что облегчает повторное использование настроек для всех твинов внутри таймлайна.

Типизация коллбеков

GSAP поддерживает множество коллбеков: onComplete, onUpdate, onStart, onRepeat. В TypeScript они имеют строгие сигнатуры:

gsap.to(element, {
    x: 100,
    duration: 1,
    onComplete: () => console.log("Анимация завершена"),
    onUpdate: (self) => console.log(self.progress())
});
  • onComplete и onStart — функции без аргументов.
  • onUpdate — получает объект твина (Tween), что позволяет использовать методы progress(), time(), isActive().

Кастомные свойства и расширяемость типов

Иногда требуется добавить пользовательские свойства для твинов. Для этого можно расширять интерфейс TweenVars:

interface CustomTweenVars extends TweenVars {
    customColor?: string;
}

const customTween: CustomTweenVars = {
    x: 50,
    customColor: "#ff0000",
    duration: 1
};

gsap.to(element, customTween as any);

Использование as any позволяет временно обойти строгую типизацию, но рекомендуется создавать собственные интерфейсы для масштабируемого кода.

Работа с GSAP Plugins в TypeScript

Многие плагины GSAP требуют отдельной типизации. Например, ScrollTrigger:

import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

gsap.to(element, {
    y: 200,
    scrollTrigger: {
        trigger: element,
        start: "top center",
        end: "bottom top",
        scrub: true
    }
});

Типы для плагинов обычно поставляются вместе с самим плагином или через @types/gsap, что позволяет TypeScript проверять корректность всех параметров, включая trigger, start, end и scrub.

Типизация массивов и сложных структур

GSAP поддерживает анимацию массивов и массивов объектов:

const elementsArray: HTMLElement[] = Array.from(document.querySelectorAll(".box"));

gsap.to(elementsArray, {
    x: 100,
    stagger: 0.2,
    duration: 1
});

TypeScript проверяет, что elementsArray соответствует TweenTarget, а stagger имеет корректный тип (number | { each: number, from?: string }).

Работа с Generics для расширенной типизации

Для более строгой типизации можно использовать Generics:

function animateElement<T extends HTMLElement>(el: T) {
    gsap.to<T>(el, { x: 100, duration: 1 });
}

const box = document.querySelector<HTMLDivElement>("#box")!;
animateElement(box);

Использование <T extends HTMLElement> позволяет сохранять тип конкретного элемента, обеспечивая автодополнение и проверку типов для методов DOM.

Советы по типизации

  • Всегда использовать TweenVars и TimelineVars для параметров анимации.
  • Использовать строгие типы для целей анимации (HTMLElement, NodeListOf<HTMLElement>).
  • Для плагинов импортировать соответствующие типы и регистрировать их через gsap.registerPlugin.
  • Расширять типы только при необходимости кастомных параметров.
  • Генерики помогают сохранять типы элементов при работе с функциями-обертками.

Эта система типизации позволяет создавать безопасные, масштабируемые и читаемые анимации на GSAP с полной поддержкой TypeScript.

Оглавление