Улучшить эту документацию ngAnimate

Модуль ngAnimate предоставляет поддержку для JavaScript, CSS3-переходов и CSS3-анимаций ключевых кадров в рамках существующих директив ядра и пользовательских директив.

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

Для просмотра анимаций необходимо определить соответствующие CSS-классы или зарегистрировать анимацию JavaScript с помощью функции myModule.animation(). Директивы, которые автоматически поддерживают анимацию: ngRepeat, ngInclude, ngIf, ngSwitch, ngShow, ngHide, ngView и ngClass. Пользовательские директивы могут использовать анимацию, используя сервис $animate.

Ниже приведён более подробный обзор поддерживаемых событий анимации, предоставляемых существующими директивами ng:

Дополнительную информацию об анимациях можно найти на странице каждой директивы.

Ниже приведён пример применения анимаций к директиве, которая поддерживает анимационные хуки:

<style type="text/css">
.slide.ng-enter, .slide.ng-leave {
  -webkit-transition:0.5s linear all;
  transition:0.5s linear all;
}

.slide.ng-enter { }        /* starting animations for enter */
.slide.ng-enter.ng-enter-active { } /* terminal animations for enter */
.slide.ng-leave { }        /* starting animations for leave */
.slide.ng-leave.ng-leave-active { } /* terminal animations for leave */
</style>

<!--
the animate service will automatically add .ng-enter and .ng-leave to the element
to trigger the CSS transition/animations
-->
<ANY class="slide" ng-include="..."></ANY>

Обратите внимание, что по умолчанию, если выполняется анимация, до завершения анимации родительского элемента любые дочерние элементы не могут быть анимированы. Это блокирующее поведение можно переопределить, разместив атрибут ng-animate-children в теге контейнера родителя.

<div class="slide-animation" ng-if="on" ng-animate-children>
  <div class="fade-animation" ng-if="on">
    <div class="explode-animation" ng-if="on">
       ...
    </div>
  </div>
</div>

Когда значение выражения on изменяется и запускается анимация, каждый из элементов будет анимирован без применения блокировки для дочерних элементов.

Запускаются ли анимации при запуске приложения?

Нет. При запуске приложения Angular отключает анимации, чтобы избежать всплеска анимаций сразу после отрисовки экрана браузером. Для этого Angular ожидает два цикла переваривания, прежде чем включить анимации. После этого любые изменения макета, вызывающие анимацию, в приложении будут вызывать анимации в обычном режиме.

Кроме того, при запуске, если система маршрутизации или любые директивы или загрузка удалённых данных (через $http), то Angular автоматически увеличит время ожидания, чтобы включить анимации после завершения всех исходящих HTTP-запросов.

Анимации, определённые в CSS

Сервис animate автоматически применяет два CSS-класса к анимируемому элементу, и эти два CSS-класса предназначены для хранения начального и конечного CSS-стилей. Поддерживаются как CSS-переходы, так и анимации ключевых кадров, которые могут использоваться вместе со структурой именования.

Следующий код демонстрирует, как выполнять анимации с помощью CSS-переходов с Angular:

<style type="text/css">
/*
 The animate class is apart of the element and the ng-enter class
 is attached to the element once the enter animation event is triggered
*/
.reveal-animation.ng-enter {
 -webkit-transition: 1s linear all; /* Safari/Chrome */
 transition: 1s linear all; /* All other modern browsers and IE10+ */

 /* The animation preparation code */
 opacity: 0;
}

/*
 Keep in mind that you want to combine both CSS
 classes together to avoid any CSS-specificity
 conflicts
*/
.reveal-animation.ng-enter.ng-enter-active {
 /* The animation code itself */
 opacity: 1;
}
</style>

<div class="view-container">
  <div ng-view class="reveal-animation"></div>
</div>

Следующий код демонстрирует, как выполнять анимации с помощью CSS-анимаций с Angular:

<style type="text/css">
.reveal-animation.ng-enter {
  -webkit-animation: enter_sequence 1s linear; /* Safari/Chrome */
  animation: enter_sequence 1s linear; /* IE10+ and Future Browsers */
}
@-webkit-keyframes enter_sequence {
  from { opacity:0; }
  to { opacity:1; }
}
@keyframes enter_sequence {
  from { opacity:0; }
  to { opacity:1; }
}
</style>

<div class="view-container">
  <div ng-view class="reveal-animation"></div>
</div>

CSS3-анимации и переходы могут использоваться вместе, и сервис animate определит правильное время длительности и задержки.

При изменении DOM сначала добавляется класс события (например, ng-enter), затем браузер подготавливается к добавлению активного класса (в данном случае ng-enter-active), который затем запускает анимацию. Модуль анимации автоматически обнаружит CSS-код, чтобы определить, когда анимация завершится. После завершения анимации оба CSS-класса будут удалены из DOM. Если браузер не поддерживает CSS-переходы или CSS-анимации, анимация начнётся и закончится немедленно, в результате чего элемент DOM окажется в конечном состоянии. Конечное состояние — это когда к элементу DOM не применены никакие CSS-классы перехода/анимации.

Анимации структурных переходов

Анимации структурных переходов (такие как вход, выход и перемещение) всегда применяют значение перехода 0s none для принудительного отображения браузером стилей, определённых в настройке (.ng-enter, .ng-leave или .ng-move)-класса. Это означает, что любые активные анимации переходов, работающие над элементом, будут прерваны, чтобы уступить место анимации входа, выхода или перемещения.

Анимации переходов на основе классов

Анимации переходов на основе классов относятся к анимациям переходов, которые запускаются при добавлении или удалении CSS-класса от элемента (через $animate.addClass, $animate.removeClass, $animate.setClass, или с помощью директив, таких как ngClass, ngModel и form). Они отличаются от структурных анимаций, поскольку не отменяют существующие анимации и не блокируют последующие переходы от отображения на том же элементе. Это различие позволяет выполнять несколько анимаций переходов на основе классов на одном элементе.

В дополнение к тому, что ngAnimate поддерживает стандартную (естественную) функциональность анимаций переходов на основе классов, ngAnimate также добавляет элементу начальные и конечные CSS-классы, чтобы помочь разработчику в дальнейшем стилизации элемента во время анимации перехода. Более ранние версии ngAnimate могли вызывать проблемы с естественными CSS-переходами, которые не отображались должным образом из-за временного блокирования переходов $animate с использованием 0s none для разрешения применения CSS-класса настройки (-add или -remove класс) без запуска анимации. Однако начиная с версии 1.3 это обходной путь в ngAnimate был удалён, и все CSS-переходы классов, не относящихся к ngAnimate, совместимы с ngAnimate.

Однако есть один особый случай при работе с переходами на основе классов в ngAnimate. При отрисовке переходов на основе классов, которые используют начальные и активные CSS-классы (например, .fade-add и .fade-add-active при добавлении .fade), убедитесь, что значение перехода определено в активном CSS-классе, а не в классе настройки.

.fade-add {
  /* remember to place a 0s transition here
     to ensure that the styles are applied instantly
     even if the element already has a transition style */
  transition:0s linear all;

  /* starting CSS styles */
  opacity:1;
}
.fade-add.fade-add-active {
  /* this will be the length of the animation */
  transition:1s linear all;
  opacity:0;
}

У класса настройки (в данном случае .fade-add) также есть свойство стиля перехода, однако его продолжительность равна нулю. Это может быть не обязательно, но если браузер не может мгновенно отобразить стиль, присутствующий в этом CSS-классе, то браузер может пытаться выполнить ненужный переход.

Однако этот обходной путь не применяется к стандартным переходам на основе классов, которые отображаются при применении к элементу CSS-класса, содержащего переход:

/* this works as expected */
.fade {
  transition:1s linear all;
  opacity:0;
}

Пожалуйста, имейте это в виду при кодировании CSS-разметки, которая будет использоваться в переходах на основе классов. Также старайтесь не смешивать два варианта анимаций на основе классов, так как CSS-код может стать слишком сложным.

Предотвращение столкновений с сторонними библиотеками

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

Вы можете предотвратить это нежелательное поведение, используя префикс для всех ваших анимационных классов:

/* prefixed with animate- */
.animate-fade-add.animate-fade-add-active {
  transition:1s linear all;
  opacity:0;
}

Затем вы настраиваете $animate для применения этого префикса:

$animateProvider.classNameFilter(/animate-/);

CSS-анимации с эффектом задержки

Анимация с эффектом задержки — это набор анимаций, которые выполняются с небольшой задержкой между последовательными операциями, что создаёт эффект занавеса. Модуль ngAnimate (версии >=1.2) поддерживает анимации с эффектом задержки, и эффект задержки может быть реализован путём создания CSS-класса ng-EVENT-stagger и присвоения этого класса базовому CSS-классу, используемому для анимации. Свойство стиля внутри класса задержки может быть свойством transition-delay или animation-delay (или оба, если ваша анимация содержит как переходы, так и анимации ключевых кадров).

.my-animation.ng-enter {
  /* standard transition code */
  -webkit-transition: 1s linear all;
  transition: 1s linear all;
  opacity:0;
}
.my-animation.ng-enter-stagger {
  /* this will have a 100ms delay between each successive leave animation */
  -webkit-transition-delay: 0.1s;
  transition-delay: 0.1s;

  /* in case the stagger doesn't work then these two values
   must be set to 0 to avoid an accidental CSS inheritance */
  -webkit-transition-duration: 0s;
  transition-duration: 0s;
}
.my-animation.ng-enter.ng-enter-active {
  /* standard transition styles */
  opacity:1;
}

Анимации с эффектом задержки работают по умолчанию в ngRepeat (при условии, что CSS-класс определён). Вне ngRepeat, чтобы использовать анимации с эффектом задержки самостоятельно, их можно запускать, вызывая несколько вызовов одного и того же события в $animate. Однако ограничения заключаются в том, что у каждого элемента должен быть один и тот же CSS-класс, а также один и тот же родительский элемент. Операция с эффектом задержки также будет сброшена, если пройдёт более 10 мс после последней анимации.

Следующий код вызовет событие ng-leave-stagger для указанного элемента:

var kids = parent.children();

$animate.leave(kids[0]); //stagger index=0
$animate.leave(kids[1]); //stagger index=1
$animate.leave(kids[2]); //stagger index=2
$animate.leave(kids[3]); //stagger index=3
$animate.leave(kids[4]); //stagger index=4

$timeout(function() {
  //stagger has reset itself
  $animate.leave(kids[5]); //stagger index=0
  $animate.leave(kids[6]); //stagger index=1
}, 100, false);

Анимации с эффектом задержки в настоящее время поддерживаются только для CSS-анимаций.

Анимации, определённые в JavaScript

В случае, если вы не хотите использовать CSS3-переходы или CSS3-анимации, или если вы хотите предложить анимации в браузерах, которые ещё не поддерживают CSS-переходы/анимации, вы можете использовать анимации JavaScript, определённые в вашем модуле AngularJS.

//!annotate="YourApp" Your AngularJS Module|Replace this or ngModule with the module that you used to define your application.
var ngModule = angular.module('YourApp', ['ngAnimate']);
ngModule.animation('.my-crazy-animation', function() {
  return {
    enter: function(element, done) {
      //run the animation here and call done when the animation is complete
      return function(cancelled) {
        //this (optional) function will be called when the animation
        //completes or when the animation is cancelled (the cancelled
        //flag will be set to true if cancelled).
      };
    },
    leave: function(element, done) { },
    move: function(element, done) { },

    //animation that can be triggered before the class is added
    beforeAddClass: function(element, className, done) { },

    //animation that can be triggered after the class is added
    addClass: function(element, className, done) { },

    //animation that can be triggered before the class is removed
    beforeRemoveClass: function(element, className, done) { },

    //animation that can be triggered after the class is removed
    removeClass: function(element, className, done) { }
  };
});

Анимации, определённые в JavaScript, создаются с помощью CSS-подобного селектора класса и набора событий, которые назначают выполнение функции обратного вызова JavaScript. При запуске анимации $animate ищет соответствующую анимацию, которая соответствует значению атрибута CSS-класса элемента, и затем выполняет соответствующую функцию события анимации (если найдена). Другими словами, если присутствующие CSS-классы на анимируемом элементе соответствуют какой-либо из анимаций JavaScript, то функция обратного вызова будет выполнена. Следует также отметить, что допускаются только простые селекторы класса (сложные селекторы класса не поддерживаются).

Внутри JavaScript-анимации ожидается возврат объекта, содержащего различные функции обратного вызова событий анимации. Как указано выше, эти обратные вызовы вызываются на основе события анимации. Поэтому, если выполняется анимация входа, и JavaScript-анимация найдена, то обратный вызов входа обработает эту анимацию (в дополнение к коду CSS-ключевой кадровой анимации или перехода, который определен с помощью таблицы стилей).

Применение стилей, специфичных для директивы, к анимации

В некоторых случаях директива или служба могут захотеть предоставить $animate дополнительные данные, которые анимация включит в свою анимацию. Например, предположим, что мы хотим отобразить анимацию, которая анимирует элемент к координатам мыши в той точке, где пользователь последний раз щелкнул. Собранием координат X/Y щелчка (через параметр события) мы можем установить стили top и left в объект и передать этот объект в вызов нашей функции $animate.addClass.

canvas.on('click', function(e) {
  $animate.addClass(element, 'on', {
    to: {
      left : e.client.x + 'px',
      top : e.client.y + 'px'
    }
  }):
});

Теперь, когда анимация выполняется, и обнаруживается переход или анимация ключевых кадров, сама анимация также включит и переведёт стили свойств left и top в свою выполняемую анимацию. Если мы хотим предоставить некоторые начальные значения анимации, мы можем сделать это, поместив стили начальной анимации в объект под названием from в том же объекте, что и анимации to.

canvas.on('click', function(e) {
  $animate.addClass(element, 'on', {
    from: {
       position: 'absolute',
       left: '0px',
       top: '0px'
    },
    to: {
      left : e.client.x + 'px',
      top : e.client.y + 'px'
    }
  }):
});

После завершения или отмены анимации объединение стилей до и после применяется к элементу. Если ngAnimate отсутствует, то стили будут применены немедленно.

Установка

Сначала включите angular-animate.js в ваш HTML:

<script src="angular.js">
<script src="angular-animate.js">

Вы можете загрузить этот файл из следующих мест:

• Google CDN
  Например: //ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/angular-animate.js
• Bower
  Например:

  bower install angular-animate@X.Y.Z

• code.angularjs.org
  Например:

  "//code.angularjs.org/X.Y.Z/angular-animate.js"

где X.Y.Z — это версия AngularJS, которую вы используете.

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

angular.module('app', ['ngAnimate']);

Теперь вы готовы приступить к работе!