Breaking changes между версиями

Библиотека AOS (Animate on Scroll) постоянно развивается, и каждая новая мажорная версия может включать изменения, которые несовместимы с предыдущими. Понимание этих изменений критично для корректной миграции проектов и предотвращения неожиданных ошибок в анимациях.

1. Изменения в инициализации

В ранних версиях AOS инициализация выглядела так:

AOS.init({
  offset: 200,
  duration: 600,
  easing: 'ease-in-sine',
  delay: 100,
});

Начиная с версии 3.x, некоторые параметры изменили своё поведение или были удалены:

  • easing: допустимые значения стали строго соответствовать CSS-функциям cubic-bezier. Старые строковые сокращения, например ease-in-sine, больше не поддерживаются.
  • once: раньше значение true означало, что анимация срабатывает один раз, теперь оно обязательно должно быть явно указано, иначе поведение меняется.
  • disable: до версии 3.x можно было передавать строку 'mobile' или 'phone'. Сейчас поддерживается только функция, возвращающая булево значение.

Пример новой инициализации:

AOS.init({
  offset: 200,
  duration: 600,
  easing: 'ease-in-out',
  delay: 100,
  once: true,
  disable: function() {
    return window.innerWidth < 768;
  }
});

2. Атрибуты анимации в HTML

data-aos атрибуты также подверглись изменениям. В версиях до 3.x допускались сокращения и альтернативные имена, начиная с 3.x:

  • data-aos="fade" теперь нужно заменять на конкретные варианты: fade-up, fade-down, fade-left, fade-right.
  • Атрибут data-aos-anchor заменен на data-aos-anchor-placement. Старый синтаксис не работает.
  • data-aos-offset теперь принимает только числовое значение в пикселях; процентные значения игнорируются.

Пример корректного HTML:

<div data-aos="fade-up" data-aos-delay="200" data-aos-duration="800" data-aos-anchor-placement="top-bottom">
  Контент
</div>

3. Изменения в API методов

В версии 2.x существовали следующие методы:

  • AOS.refresh() — обновлял позиции элементов.
  • AOS.refreshHard() — полностью пересоздавал все анимации.

В версии 3.x метод refreshHard() был удалён. Для полной переработки анимаций теперь используется:

AOS.refresh();

Синтаксис и аргументы также изменены: метод refresh() больше не принимает аргументы. Любые попытки передать селекторы приведут к игнорированию.

4. События и обратные вызовы

Ранее библиотека предоставляла события:

document.addEventListener('aos:in', ({ detail }) => {
  console.log('Элемент вошёл в область видимости', detail);
});

Изменения в версии 3.x:

  • Событие aos:in больше не поддерживает объект detail с информацией о позиции.
  • Для получения элемента теперь используется event.target.
  • Добавлены новые события: aos:out и aos:destroyed для отслеживания выхода элемента из зоны видимости и удаления анимации соответственно.

Пример нового обработчика:

document.addEventListener('aos:in', function(event) {
  console.log('Элемент анимирован:', event.target);
});

5. Совместимость с мобильными устройствами

Раньше параметр disable: 'mobile' автоматически отключал анимации на всех мобильных устройствах. В новых версиях логика стала более гибкой, но одновременно более строгой:

  • Параметр принимает только функцию: disable: () => boolean.
  • Для отключения на всех устройствах с шириной меньше 768px:
AOS.init({
  disable: () => window.innerWidth < 768
});

Использование старого синтаксиса disable: 'mobile' больше не работает и может вызывать ошибки при инициализации.

6. Стиль анимаций и CSS-классы

AOS с версии 3.x перешла на более строгую систему классов:

  • aos-animate теперь добавляется только после полной готовности анимации.
  • Старые классы вроде aos-fade автоматически заменяются на новые комбинации fade-up, fade-down и т.д.
  • Пользовательские CSS-правила могут требовать обновления селекторов из-за изменений структуры классов в DOM.

Пример адаптации CSS:

[data-aos="fade-up"].aos-animate {
  transform: translateY(0);
  opacity: 1;
  transition: all 0.6s ease-in-out;
}

7. Итоговые рекомендации по миграции

  • Перепроверить все data-aos-атрибуты и заменить устаревшие значения.
  • Явно указывать once и disable при инициализации.
  • Использовать новые события вместо старых detail объектов.
  • Обновить CSS для соответствия новым классам.
  • Заменить вызовы AOS.refreshHard() на AOS.refresh().

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

Оглавление