Типичные ошибки и их решения

Неверное подключение библиотеки Частая ошибка — отсутствие корректного подключения GSAP или использование устаревшей версии. Для работы с последними возможностями следует подключать библиотеку через официальный CDN или устанавливать через npm:

import { gsap } from "gsap";

Использование старого синтаксиса (TweenLite, TweenMax) может привести к непредсказуемому поведению при попытке использовать новые плагины.

Неправильный селектор элементов GSAP требует правильного указания элементов DOM. Ошибкой является использование переменных, не содержащих DOM-элемент или NodeList:

// Некорректно
gsap.to("myDiv", { x: 100 }); // селектор без # или . не сработает

// Корректно
gsap.to("#myDiv", { x: 100 });

Проблемы с последовательностью анимаций

Одновременное использование delay и timeline При комбинировании delay в gsap.to() с Timeline часто возникает эффект “разрыва” последовательности. Для синхронизации анимаций лучше использовать методы таймлайна:

const tl = gsap.timeline();
tl.to("#box", { x: 100 })
  .to("#box", { y: 50 });

Здесь delay не нужен — таймлайн автоматически управляет очередностью.

Перезапись анимаций на один элемент Когда несколько анимаций применяются к одному элементу без таймлайна, предыдущие могут быть перезаписаны. Решение — использовать overwrite:

gsap.to("#box", { x: 100, overwrite: "auto" });
gsap.to("#box", { y: 50, overwrite: "auto" });

Ошибки в использовании свойств

Недопустимые значения GSAP не проверяет тип значения автоматически, поэтому передача строки вместо числа или наоборот приводит к отсутствию анимации:

// Ошибочно
gsap.to("#box", { x: "hundred" });

// Правильно
gsap.to("#box", { x: 100 });

Применение неподдерживаемых CSS-свойств Не все CSS-свойства анимируются GSAP. Попытка анимации свойства display или position без альтернативного подхода не даст результата. Для управления видимостью используется autoAlpha:

gsap.to("#box", { autoAlpha: 1 }); // сочетает opacity и visibility

Ошибки при работе с функциями обратного вызова

Неправильный контекст this Внутри функций onComplete, onUpdate или onStart значение this не всегда ссылается на элемент. Необходимо использовать параметры или стрелочные функции для сохранения контекста:

gsap.to("#box", { 
  x: 100, 
  onComplete: function() { console.log(this); } // this указывает на tween, не на элемент
});

// Лучше
gsap.to("#box", { 
  x: 100, 
  onComplete: () => console.log("#box выполнено")
});

Синхронизация с асинхронным кодом Попытка запустить анимацию и сразу читать свойства DOM может привести к неправильным значениям. Решение — использовать onComplete или then:

gsap.to("#box", { x: 100 }).then(() => {
  console.log("Анимация завершена, можно читать свойства");
});

Ошибки при использовании плагинов

Неинициализированные плагины Многие плагины GSAP, такие как ScrollTrigger или MotionPathPlugin, требуют явного подключения и регистрации:

import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

Без регистрации анимации с использованием этих плагинов не сработают, и в консоли появятся ошибки.

Конфликты версий плагинов и библиотеки Если версия плагина и основной GSAP не совпадает, могут возникнуть неожиданные баги. Всегда следует использовать совместимые версии из официального источника.

Типичные визуальные баги

Анимация “дёргается” или не плавная Причины могут быть следующие:

  • слишком частое обновление свойств, конфликт с CSS-трансформациями;
  • использование position: absolute с некорректными координатами;
  • изменение свойств, которые вызывают перерисовку документа (например, width и height вместо scale).

Решение: анимировать свойства GPU-дружелюбные (x, y, scale, rotation) и использовать will-change в CSS.

Оглавление