Улучшить документацию Просмотреть исходный код $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() vs runner.then()

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

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