.animate()


.animate( properties [, duration ] [, easing ] [, complete ] )Возвращает: jQuery

Описание: Выполняет произвольную анимацию набора CSS свойств.

  • Добавлен в версии: 1.0.animate( properties [, duration ] [, easing ] [, complete ] )

    • properties
      Тип: PlainObject
      Объект с CSS свойствами и их значениями, для которых будет выполнена анимация.
    • duration (значение по умолчанию: 400)
      Тип: Number или String
      Строка или число определяющее длительность анимации.
    • easing (значение по умолчанию: swing)
      Тип: String
      Строка указывающая какая функция будет использована для анимации.
    • complete
      Тип: Function()
      Функция, которая будет вызвана после окончания анимации, вызывается для каждого элемента.
  • Добавлен в версии: 1.0.animate( properties, options )

    • properties
      Тип: PlainObject
      Объект с CSS свойствами и их значениями, для которых будет выполнена анимация.
    • options
      Тип: PlainObject
      Ассоциативный массив с дополнительными опциями.
      • duration (значение по умолчанию: 400)
        Тип: Number или String
        Строка или число определяющее длительность анимации.
      • easing (значение по умолчанию: swing)
        Тип: String
        Строка указывающая какая функция будет использована для анимации.
      • queue (значение по умолчанию: true)
        Тип: Boolean или String
        Булевый флаг, означающий следует ли поместить анимацию в очередь выполняемых эффектов. Если значение false, то анимация запустится немедленно. Начиная с jQuery 1.7, опция queue может также принимать строку, в этом случае анимация будет добавлена в очередь представленная этой строкой. Когда используется произвольное имя в очереди - анимация не запускается автоматически, Вы должны вызвать метод .dequeue("queuename") для ее запуска.
      • specialEasing
        Тип: PlainObject
        Объект содержащий один или несколько CSS свойств и определяющий соотвествующую функцию анимации для конкретного CSS свойства. (Добавлен в версии: 1.4)
      • step
        Тип: Function( Number now, Tween tween )
        Функция, которая вызывается для каждого анимированного свойства каждого анимационного элемента. Эта функция дает возможность изменять объект Tween, чтобы изменить значение свойства, прежде чем оно установлено.
      • progress
        Тип: Function( Promise animation, Number progress, Number remainingMs )
        Функция, которая вызывается после каждого шага анимации, только один раз для анимационного элемента, независимо от количества анимированных свойств. (Добавлен в версии: 1.8)
      • complete
        Тип: Function()
        Функция, которая вызывается один раз для анимации на элементе при ее завершении.
      • start
        Тип: Function( Promise animation )
        Функция, которая вызывается перед началом анимации. (Добавлен в версии: 1.8)
      • done
        Тип: Function( Promise animation, Boolean jumpedToEnd )
        Функция, которая вызывается после завершения анимации на элементе. (Добавлен в версии: 1.8)
      • fail
        Тип: Function( Promise animation, Boolean jumpedToEnd )
        Функция, которая вызывается если анимация завершается ошибкой. (Добавлен в версии: 1.8)
      • always
        Тип: Function( Promise animation, Boolean jumpedToEnd )
        Функция, которая вызывается в любом случае - либо при завершении анимации, либо при ее отмене без выполенения. (Добавлен в версии: 1.8)

Метод .animate() позволяет создать эффект анимации на любое числовое CSS свойство элемента. Единственным необходимым параметром является объект с CSS свойствами. Этот объект похож на тот что передается в метод .css(), за исключением того, что диапазон свойств более ограничен.

Анимационные свойства и значения

Все анимационные свойства должны быть анимированы при помощи единичного числового значения, за исключением случаев указанных ниже; большинство не числовых свойств не могут быть анимированы при помощи базового функционала jQuery (Например width, height или left могут быть анимированы, но background-color не может, за исключением использования плагина jQuery.Color). Значения свойств рассматриваются как количество пикселей, если не указано иное. Единицы измерения em и % могут быть указаны, там где это применимо.

В дополнение к свойствам стиля, некоторые не стилевые свойстваs, такие как scrollTop и scrollLeft, а также пользовательские свойства, могут быть анимированы.

Сокращенные CSS свойства (такие как font, background, border) не полностью поддерживаются. Например, если Вы хотите анимировать ширину границ, то стиль и изначальная ширина границы должны быть заданы заранее. Или, если Вы хотите анимировать размер шрифта, Вы должны использовать fontSize или CSS эквивалент 'font-size' а не просто 'font'.

В дополнение к числовым значениям, каждое свойство может принять строку: 'show', 'hide' или 'toggle'. Эти сокращения позволяют произвольную анимацию скрытия или отображения, которая учитывает тип отображения элемента. Для того чтобы использовать встроенное отслеживание состояния отображения свойства, строка 'toggle' должна быть задана в качестве значения анимируемого CSS свойства.

Анимированные свойства также могут быть относительными. Если значение задано с ведущей последовательностью символов += или -=, то целевое значение вычисляется путем сложения или вычитания заданного числа от текущего значения свойства.

Важно: В отличие от сокращенных методов анимации, таких как .slideDown() и .fadeIn(), метод .animate() не делает скрытие элемента как часть эффекта. Например, в случае $( "someElement" ).hide().animate({height: "20px"}, 500), анимация будет запущена, но элемент будет оставаться скрытым.

Длительность

Длительность задается в милисекундах. Более высокие значения означает более медленную анимацию, а не быструю. Значение по умолчанию 400 милисекунд. Строки 'fast' и 'slow' могут быть использованы для указания длительности 200 и 600 милисекунд соответственно.

Функции обратного вызова

Если заданы start, step, progress, complete, done, fail и always функции обратного вызова, то они будут вызваны для каждого анимируемого элемента; this в этих функциях будет указывать на анимируемый DOM-элемент. Если в выборке нет элементов, то функции обратного вызова не будут выполняться. Если анимируются несколько элементов, то обратный вызов выполняется один раз для каждого элемента, а не один раз для анимации в целом. Используйте метод .promise() для получения объекта Promise и прикрепления функций обратных вызовов.

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

Анимация любого элемента, например простое изображение:

1
2
3
4
5
<div id="clickme">
Нажмите здесь
</div>
<img id="book" src="book.png" alt="" width="100" height="123"
style="position: relative; left: 10px;">

Для одновременной анимации прозрачности, отступа слева и высоты картинки:

1
2
3
4
5
6
7
8
9
$( "#clickme" ).click(function() {
$( "#book" ).animate({
opacity: 0.25,
left: "+=50",
height: "toggle"
}, 5000, function() {
// Animation complete.
});
});

Иллюстрация заданного эффекта анимации
Картинка 1 - Иллюстрация заданного эффекта анимации

Обратите внимание, что целевое значение свойства height равно 'toggle'. Так как изображение было видно прежде, анимация сокращает высоту до 0 чтобы скрыть его. Второе нажатие затем обратит этот переход:

Иллюстрация заданного эффекта анимации
Картинка 2 - Иллюстрация заданного эффекта анимации

Свойство opacity картинки уже равно его целевому значению, так что это свойство не анимируется при втором клике. Так как значение свойства left является относительным значением, то картинка сдвигается далее направо во время второй анимации.

Свойства направлений (top, right, bottom, left) не имеют никакого заметного влияния на элементы, если их свойство position установленно в значение static (значение по умолчанию).

Важно: библиотека jQuery UI расширяет метод .animate() разрешая анимировать некоторые нечисловые свойства, например цветовые свойства. jQuery UI также включает механизм для указания специфических анимаций через CSS классы, а не отдельные аттрибуты.

Важно: если пытаться анимировать элемент с высотой или шириной равной 0px, где содержимое элемента показывается из-за переполнения (overflow), jQuery может обрезать переполнения во время анимации. Устанавив размеры исходного элемента, спрятанного до анимации, можно гарантировать, что анимация пройдет гладко. clearfix может быть использован для автоматического исправления размеров вашего основного элемента без необходимости устанавливать их вручную.

Шаговая функция

Вторая версия метода .animate() предоставляет опцию step — функцию обратного вызова, которая вызывается на каждом шаге анимации. Эта функция полезна для включения произвольных типов анимаций или изменения анимации, в момент ее выполнения. Она принимает два аргумента (now и fx), а также this указывает на анимируемый DOM-элемент.

  • now: числовое значение анимируемого свойства на каждом шаге
  • fx: ссыдка на прототип объекта jQuery.fx, который содержит ряд свойств, таких как elem для анимируемого элемента, start и end для первого и последнего значения анимируемого свойства соотвественно и prop для анимируемого свойства.

Обратите внимание что функция step вызывается для каждого анимируемого свойства на каждом анимируемом элементе. Например, даны два списка, функция step вызывается четыре раза на каждый шаг анимации:

1
2
3
4
5
6
7
8
9
$( "li" ).animate({
opacity: .5,
height: "50%"
}, {
step: function( now, fx ) {
var data = fx.elem.id + " " + fx.prop + ": " + now;
$( "body" ).append( "<div>" + data + "</div>" );
}
});

Функция исчезания (Easing)

Оставшийся параметр метода .animate() это строка с именем используемой функции исчезания (easing). Функция easingопределяет скорость с которой анимация прогрессирует в различных точках в пределах анимации. В базовом функционале jQuery поставляется две такие функции: swing, используемая по умолчанию, и linear с равномерным изменением анимации. Больше easing функций доступны при использовании плагинов, в первую очередь jQuery UI suite.

Функция исчезания для каждого свойства

Начиная с jQuery версии 1.4, Вы можете установить easing функция по отдельности для каждого анимируемого свойства при вызове .animate(). В первой версии метода .animate(), каждое свойство может принимать массив в качестве значений: первый член массива является названием CSS свойства, второй член массива имя easing функции. Если easing функция не определена для определенного свойства, то используется значение из метода .animate() или его значение по умолчанию. Если аргумент easing не установлен, то используется значение по умолчанию swing.

Например, чтобы одновременно анимировать ширину и высоту с swing easing функцией и прозрачность с linear easing функцией:

1
2
3
4
5
6
7
8
9
$( "#clickme" ).click(function() {
$( "#book" ).animate({
width: [ "toggle", "swing" ],
height: [ "toggle", "swing" ],
opacity: "toggle"
}, 5000, "linear", function() {
$( this ).after( "<div>Анимация завершена.</div>" );
});
});

Во второй версии метода .animate(), объект с опциями может включать свойство specialEasing, который сам по себе является объектом свойств CSS и их соответствующих easing функций. Например, для одновременной анимации ширины при помощи linear easing функции и высоты при помощи easeOutBounce easing функции:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$( "#clickme" ).click(function() {
$( "#book" ).animate({
width: "toggle",
height: "toggle"
}, {
duration: 5000,
specialEasing: {
width: "linear",
height: "easeOutBounce"
},
complete: function() {
$( this ).after( "<div>Анимация завершена.</div>" );
}
});
});

Как ранее отмечалось, для easeOutBounce easing функции требуется подключение соотвествующего плагина.

Дополнительные замечания:

  • Все эффекты jQuery, включая .animate(), могут быть отключены глобально при помощи настройки jQuery.fx.off = true, которая фактически устанавливает длительность анимации в значение 0. Более подробно это описано на странице jQuery.fx.off.

Примеры использования