Установка и регистрация плагина

Установка GSAP через npm

Для работы с GSAP в современных проектах на JavaScript оптимально использовать пакетный менеджер npm. Это позволяет интегрировать библиотеку в сборщики модулей, такие как Webpack, Parcel или Vite.

npm install gsap

После установки можно импортировать основные функции и объекты библиотеки:

import gsap from "gsap";

Если требуется использование конкретного плагина, его можно импортировать отдельно:

import { ScrollTrigger } from "gsap/ScrollTrigger";

Подключение через CDN

Для быстрых прототипов или небольших проектов можно использовать CDN. В этом случае скрипт подключается напрямую в HTML:

<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.2/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.2/dist/ScrollTrigger.min.js"></script>

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

Регистрация плагинов

Некоторые плагины GSAP не активны по умолчанию и требуют явной регистрации. Для этого используется метод gsap.registerPlugin().

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

Ключевые моменты регистрации:

  • Плагины, такие как ScrollTrigger, Draggable, SplitText, не активны без регистрации.
  • Метод registerPlugin принимает один или несколько плагинов через запятую.
  • Регистрация должна происходить до использования функций плагина.

Пример регистрации нескольких плагинов:

import { ScrollTrigger, Draggable } from "gsap/all";

gsap.registerPlugin(ScrollTrigger, Draggable);

Особенности подключения в разных средах

  1. ESM (модули) При использовании сборщиков модулей рекомендуется импортировать только те плагины, которые необходимы, для уменьшения размера бандла.

    import gsap from "gsap";
import { MotionPathPlugin } from "gsap/MotionPathPlugin";

gsap.registerPlugin(MotionPathPlugin);

  2. Vanilla JS через глобальный объект При подключении через CDN, плагины автоматически добавляются в глобальный объект gsap, но все равно требуют регистрации:

    gsap.registerPlugin(ScrollTrigger);

Проверка успешной регистрации

После регистрации можно проверить доступность плагина через консоль:

console.log(gsap.plugins.ScrollTrigger); // Должно вывести объект плагина

Если вывод undefined, регистрация не прошла или плагин не был подключен.

Практические советы

  • Для плагинов, требующих лицензии (например, DrawSVGPlugin), необходимо указывать лицензионный токен перед регистрацией.
  • Регистрация выполняется один раз за сессию загрузки страницы или модуля, повторная регистрация не требуется.
  • При использовании нескольких плагинов лучше регистрировать их все в одном месте, чтобы избежать путаницы и ошибок при анимации.

Импорт всех плагинов сразу

GSAP предоставляет возможность импортировать весь набор плагинов через пакет gsap/all, однако это увеличивает размер финального бандла. Используется в проектах, где важна простота прототипирования, а не оптимизация:

import gsap from "gsap";
import * as AllPlugins from "gsap/all";

gsap.registerPlugin(...Object.values(AllPlugins));

Совместимость с TypeScript

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

npm install --save-dev @types/gsap

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

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

gsap.to(".box", {
  x: 300,
  scrollTrigger: ".box"
});

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

Оглавление