Улучшить документацию Посмотреть исходный код $animateCss

Сервис $animateCss — полезный инструмент для запуска настраиваемых анимаций и ключевых кадров на основе CSS из JavaScript-анимации или непосредственно из директивы. Цель $animateCss — НЕ обойти механизмы работы $animate и ngAnimate, а предоставить возможность использовать существующие анимации и директивы для создания более сложных анимаций, управляемых исключительно кодом CSS.

Обратите внимание, что анимации, запущенные с помощью $animateCss, смогут отображаться только в браузерах, поддерживающих CSS-переходы и/или анимации ключевых кадров (плохая новость для IE9 и более ранних версий).

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

Опять же, $animateCss предназначен для использования внутри зарегистрированной JavaScript-анимации, работающей с ngAnimate. Можно использовать $animateCss напрямую внутри директивы, однако Angular не будет автоматически управлять отменением анимаций или предотвращением запуска анимаций на дочерних элементах. Для корректной работы используйте $animate для запуска анимации и настройте JavaScript-анимацию, которая вставляет $animateCss для запуска CSS-анимации.

Ниже показано, как создать анимацию складывания элемента с помощью ng-if.

<!-- notice the `fold-animation` CSS class -->
<div ng-if="onOff" class="fold-animation">
  This element will go BOOM
</div>
<button ng-click="onOff=true">Fold In</button>

Теперь создадим JavaScript-анимацию, которая запустит CSS-переход:

ngModule.animation('.fold-animation', ['$animateCss', function($animateCss) {
  return {
    enter: function(element, doneFn) {
      var height = element[0].offsetHeight;
      return $animateCss(element, {
        from: { height:'0px' },
        to: { height:height + 'px' },
        duration: 1 // one second
      });
    }
  }
}]);

Более продвинутые применения

$animateCss — это базовый код, который ngAnimate использует для работы анимаций на основе CSS. Поэтому такие CSS-хуки, как .ng-EVENT, .ng-EVENT-active, .ng-EVENT-stagger, можно вызывать с помощью $animateCss через JavaScript-код.

Это также означает, что любые комбинации добавления классов, удаления классов, установки стилей, динамической установки анимации ключевых кадров, применения жестко заданных значений длительности или задержки, изменения ускорения анимации или применения анимации с отставанием — все это варианты работы с $animateCss. Сам сервис достаточно интеллектуален, чтобы определить комбинацию параметров и проанализировать свойства стилей элемента для обеспечения функционирования анимации на основе CSS.

В примере ниже показана более сложная версия .fold-animation из предыдущего примера:

ngModule.animation('.fold-animation', ['$animateCss', function($animateCss) {
  return {
    enter: function(element, doneFn) {
      var height = element[0].offsetHeight;
      return $animateCss(element, {
        addClass: 'red large-text pulse-twice',
        easing: 'ease-out',
        from: { height:'0px' },
        to: { height:height + 'px' },
        duration: 1 // one second
      });
    }
  }
}]);

Поскольку мы добавляем/удаляем CSS-классы, CSS-переход также их учтет:

/* since a hardcoded duration value of 1 was provided in the JavaScript animation code,
the CSS classes below will be transitioned despite them being defined as regular CSS classes */
.red { background:red; }
.large-text { font-size:20px; }

/* we can also use a keyframe animation and $animateCss will make it work alongside the transition */
.pulse-twice {
  animation: 0.5s pulse linear 2;
  -webkit-animation: 0.5s pulse linear 2;
}

@keyframes pulse {
  from { transform: scale(0.5); }
  to { transform: scale(1.5); }
}

@-webkit-keyframes pulse {
  from { -webkit-transform: scale(0.5); }
  to { -webkit-transform: scale(1.5); }
}

С учетом этой сложной комбинации CSS-классов, стилей и параметров $animateCss определит все и запустит анимацию.

Как обрабатываются параметры

$animateCss очень гибкий и умный при определении параметров, которые нужно применить к элементу, чтобы обеспечить работу анимации с заданными параметрами. Например, если мы добавляем класс, содержащий значение ключевого кадра, и хотим также анимировать некоторые встроенные стили, используя свойства from и to.

var animator = $animateCss(element, {
  from: { background:'red' },
  to: { background:'blue' }
});
animator.start();

.rotating-animation {
  animation:0.5s rotate linear;
  -webkit-animation:0.5s rotate linear;
}

@keyframes rotate {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

@-webkit-keyframes rotate {
  from { -webkit-transform: rotate(0deg); }
  to { -webkit-transform: rotate(360deg); }
}

Здесь не хватает установленного перехода (ни в CSS-коде, ни в параметрах $animateCss). Длительность анимации будет определяться стилями ключевых кадров в CSS-классе, который добавляется. В этом случае $animateCss автоматически создаст встроенный стиль перехода, соответствующий длительности, определенной из стиля ключевого кадра (который есть в CSS-классе, добавляемом в элемент), а затем подготовит анимации перехода и ключевого кадра для параллельного выполнения на элементе. Затем, во время анимации, указанные стили CSS from и to будут применяться и распределяться по анимации перехода и ключевого кадра.

Что возвращается

$animateCss работает в два этапа: подготовка и анимация. Поэтому, когда $animateCss вызывается в первый раз, анимация еще не запускается. Здесь просто происходит подготовка элемента к анимации (т.е. на элементе добавляются и удаляются сгенерированные CSS-классы). После вызова $animateCss возвращается объект со следующими свойствами:

var animator = $animateCss(element, { ... });

А теперь, как выглядит содержимое переменной animator.

{
  // starts the animation
  start: Function,

  // ends (aborts) the animation
  end: Function
}

Чтобы запустить анимацию, необходимо выполнить animation.start(), которое вернет промис, на котором можно отследить завершение анимации. Если мы не хотим запускать анимацию, мы ДОЛЖНЫ выполнить animation.end() для очистки элемента (поскольку некоторые CSS-классы и стили могут быть применены к элементу во время фазы подготовки). Обратите внимание, что все остальные свойства, такие как длительность, задержка, переходы и ключевые кадры, являются просто свойствами, и изменение их не переконфигурирует параметры анимации.

runner.done() против runner.then()

Документировано, что animation.start() возвращает объект промиса, и это верно, однако также доступен дополнительный метод runner, называемый .done(callbackFn). Метод done работает так же, как .finally(callbackFn), но не запускает переваривание. Поэтому по соображениям производительности всегда лучше использовать runner.done(callback) вместо runner.then(), runner.catch() или runner.finally(), если вам не нужен цикл переваривания.

Для упрощения ngAnimate модифицировал API JavaScript-анимаций, чтобы распознавать, когда экземпляр runner возвращается из $animateCss (поэтому нет необходимости вызывать runner.done(doneFn) в вашем коде JavaScript-анимации). Проверьте код анимации выше по ссылке анимация, чтобы увидеть, как это работает.