.animate() | jQuery API Documentation

.animate( properties [, duration ] [, easing ] [, complete ] )返回: jQuery

描述: 执行一组 CSS 属性的自定义动画。

版本添加: 1.0.animate( properties [, duration ] [, easing ] [, complete ] )
- properties
  
  类型: PlainObject
  
  CSS 属性和值对象，动画将向其移动。
- duration (默认: 400)
  
  类型: Number 或 String
  
  一个字符串或数字，决定动画的持续时间。
- easing (默认: swing)
  
  类型: 字符串
  
  一个字符串，指示在过渡过程中使用的缓动函数。
- complete
  
  类型：Function()
  
  一个函数，当动画完成时调用，为每个匹配的元素调用一次。
版本添加: 1.0.animate( properties, options )
- properties
  
  类型: PlainObject
  
  CSS 属性和值对象，动画将向其移动。
- options
  
  类型: PlainObject
  
  要传递给方法的附加选项的映射。
  - duration (默认: 400)
    
    类型: Number 或 String
    
    一个字符串或数字，决定动画的持续时间。
  - easing (默认: swing)
    
    类型: 字符串
    
    一个字符串，指示在过渡过程中使用的缓动函数。
  - queue (默认: true)
    
    类型: Boolean 或 String
    
    一个布尔值，指示动画是否应放入效果队列。如果为 false，则动画将立即开始。从 jQuery 1.7 开始，queue 选项也可以接受一个字符串，在这种情况下，动画会被添加到由该字符串表示的队列中。当使用自定义队列名称时，动画不会自动开始；您必须调用 .dequeue("queuename") 来启动它。
  - specialEasing
    
    类型: PlainObject
    
    一个对象，包含一个或多个由 properties 参数定义的 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 )
    
    当一个元素的动画完成时（其 Promise 对象已解析）将被调用的函数。 (版本添加: 1.8)
  - fail
    
    类型: Function( Promise animation, Boolean jumpedToEnd )
    
    当一个元素的动画未能完成时（其 Promise 对象被拒绝）将被调用的函数。 (版本添加: 1.8)
  - always
    
    类型: Function( Promise animation, Boolean jumpedToEnd )
    
    当一个元素的动画完成或停止而未完成时（其 Promise 对象已解析或被拒绝）将被调用的函数。 (版本添加: 1.8)

.animate() 方法允许我们对任何数字 CSS 属性创建动画效果。唯一必需的参数是一个 CSS 属性的普通对象。这个对象类似于可以发送给 .css() 方法的对象，但属性范围更具限制性。

动画属性和值

所有动画属性都应动画到单个数字值，除非另有说明；大多数非数字属性不能使用基本的 jQuery 功能进行动画（例如，width、height 或 left 可以动画，但 background-color 不能，除非使用 jQuery.Color 插件）。属性值被视为像素数，除非另有指定。单位 em 和 % 可以在适用时指定。

除了样式属性，一些非样式属性如 scrollTop 和 scrollLeft，以及自定义属性，也可以动画。

不支持速记 CSS 属性（例如 font, background, border）。例如，如果你想动画渲染的边框宽度，至少必须事先设置边框样式和非“auto”的边框宽度。或者，如果你想动画字体大小，你应该使用 fontSize 或等效的 CSS 'font-size'，而不是简单的 'font'。

除了数字值，每个属性都可以接受字符串 'show'、'hide' 和 'toggle'。这些快捷方式允许自定义隐藏和显示动画，考虑到元素的显示类型。为了使用 jQuery 内置的切换状态跟踪，'toggle' 关键字必须始终作为动画属性的值。

动画属性也可以是相对的。如果提供的值带有前导 += 或 -= 字符序列，则通过将给定数字添加到或减去属性的当前值来计算目标值。

注意: 与 .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，你可以将回调附加到该 promise，该回调会为任意大小的动画集（包括零元素）触发一次。

基本用法

动画任何元素，例如一个简单的图像

	
					<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123"
  style="position: relative; left: 10px;">

同时动画图像的不透明度、左偏移量和高度

	
					$( "#clickme" ).on( "click", function() {
  $( "#book" ).animate({
    opacity: 0.25,
    left: "+=50",
    height: "toggle"
  }, 5000, function() {
    // Animation complete.
  });
});

请注意，height 属性的目标值是 'toggle'。由于图像之前是可见的，动画将高度缩小到 0 以隐藏它。第二次点击然后反转此过渡

图像的 opacity 已经达到其目标值，因此第二次点击时不会动画此属性。由于 left 的目标值是相对值，因此在此第二次动画期间图像向右移动得更远。

如果元素的 position 样式属性是 static（默认情况下是这样），则方向属性（top、right、bottom、left）对元素没有明显效果。

注意: jQuery UI 项目扩展了 .animate() 方法，允许动画一些非数字样式（例如颜色）。该项目还包括通过 CSS 类而不是单个属性指定动画的机制。

注意: 如果尝试动画高度或宽度为 0px 的元素，且元素的内容由于溢出而可见，jQuery 可能会在动画期间裁剪此溢出。但是，通过固定要隐藏的原始元素的尺寸，可以确保动画平稳运行。可以使用 clearfix 自动固定主元素的尺寸，而无需手动设置。

步进函数

.animate() 的第二个版本提供了一个 step 选项 — 一个在动画的每一步触发的回调函数。此函数对于启用自定义动画类型或在动画发生时更改动画非常有用。它接受两个参数（now 和 fx），并且 this 设置为正在动画的 DOM 元素。

now: 在每一步动画属性的数字值
fx: 对 jQuery.fx 原型对象的引用，其中包含许多属性，例如用于动画元素的 elem、用于动画属性的第一个和最后一个值的 start 和 end，以及用于动画属性的 prop。

请注意，step 函数为每个动画元素上的每个动画属性调用。例如，给定两个列表项，step 函数在动画的每一步触发四次

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

缓动

.animate() 的其余参数是一个字符串，命名要使用的缓动函数。缓动函数指定动画在动画中不同点的进展速度。jQuery 库中唯一的缓动实现是默认的，称为 swing，以及一个以恒定速度进展的，称为 linear。使用插件可以获得更多的缓动函数，最著名的是 jQuery UI 套件。

按属性缓动

从 jQuery 1.4 版开始，你可以在单个 .animate() 调用中设置按属性的缓动函数。在 .animate() 的第一个版本中，每个属性都可以将其值设置为一个数组：数组的第一个成员是 CSS 属性，第二个成员是缓动函数。如果未为特定属性定义按属性的缓动函数，它将使用 .animate() 方法的可选缓动参数的值。如果未定义缓动参数，则使用默认的 swing 函数。

例如，同时使用 swing 缓动函数动画宽度和高度，并使用 linear 缓动函数动画不透明度

	
					$( "#clickme" ).on( "click", function() {
  $( "#book" ).animate({
    width: [ "toggle", "swing" ],
    height: [ "toggle", "swing" ],
    opacity: "toggle"
  }, 5000, "linear", function() {
    $( this ).after( "<div>Animation complete.</div>" );
  });
});

在 .animate() 的第二个版本中，options 对象可以包含 specialEasing 属性，它本身是一个 CSS 属性及其相应缓动函数的对象。例如，同时使用 linear 缓动函数动画宽度和使用 easeOutBounce 缓动函数动画高度

	
					$( "#clickme" ).on( "click", function() {
  $( "#book" ).animate({
    width: "toggle",
    height: "toggle"
  }, {
    duration: 5000,
    specialEasing: {
      width: "linear",
      height: "easeOutBounce"
    },
    complete: function() {
      $( this ).after( "<div>Animation complete.</div>" );
    }
  });
});

如前所述，easeOutBounce 函数需要一个插件。

附加说明

所有 jQuery 效果，包括 .animate()，都可以通过设置 jQuery.fx.off = true 来全局关闭，这有效地将持续时间设置为 0。有关更多信息，请参阅 jQuery.fx.off。

示例

示例 1

点击按钮动画 div，带有许多不同的属性。

	
		
				
				
				
				
					<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>animate demo</title>
  <style>
  div {
    background-color: #bca;
    width: 100px;
    border: 1px solid green;
  }
  </style>
  <script src="https://code.jquery.com/jquery-4.0.0.js"></script>
</head>
<body>
 
<button id="go">&raquo; Run</button>
<div id="block">Hello!</div>
 
<script>
// Using multiple unit types within one animation.
 
$( "#go" ).on( "click", function() {
  $( "#block" ).animate({
    width: "70%",
    opacity: 0.4,
    marginLeft: "0.6in",
    fontSize: "3em",
    borderWidth: "10px"
  }, 1500 );
});
</script>
 
</body>
</html>

				
			

	

演示

示例 2

动画 div 的 left 属性，使用相对值。多次点击按钮以查看排队的相对动画。

	
		
				
				
				
				
					<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>animate demo</title>
  <style>
  div {
    position: absolute;
    background-color: #abc;
    left: 50px;
    width: 90px;
    height: 90px;
    margin: 5px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-4.0.0.js"></script>
</head>
<body>
 
<button id="left">&laquo;</button>
<button id="right">&raquo;</button>
<div class="block"></div>
 
<script>
$( "#right" ).on( "click", function() {
  $( ".block" ).animate({ "left": "+=50px" }, "slow" );
});
 
$( "#left" ).on( "click", function(){
  $( ".block" ).animate({ "left": "-=50px" }, "slow" );
});
</script>
 
</body>
</html>

				
			

	

演示

示例 3

第一个按钮显示了未排队的动画如何工作。它在字体大小增加的同时将 div 扩展到 90% 宽度。一旦字体大小更改完成，边框动画将开始。第二个按钮开始传统的链式动画，其中每个动画将在前一个元素上的动画完成后开始。

	
		
				
				
				
				
					<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>animate demo</title>
  <style>
  div {
    background-color: #bca;
    width: 200px;
    height: 1.1em;
    text-align: center;
    border: 2px solid green;
    margin: 3px;
    font-size: 14px;
  }
  button {
    font-size: 14px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-4.0.0.js"></script>
</head>
<body>
 
<button id="go1">&raquo; Animate Block1</button>
<button id="go2">&raquo; Animate Block2</button>
<button id="go3">&raquo; Animate Both</button>
<button id="go4">&raquo; Reset</button>
<div id="block1">Block1</div>
<div id="block2">Block2</div>
 
<script>
$( "#go1" ).on( "click", function() {
  $( "#block1" )
    .animate({
      width: "90%"
    }, {
      queue: false,
      duration: 3000
    })
    .animate({ fontSize: "24px" }, 1500 )
    .animate({ borderRightWidth: "15px" }, 1500 );
});
 
$( "#go2" ).on( "click", function() {
  $( "#block2" )
    .animate({ width: "90%" }, 1000 )
    .animate({ fontSize: "24px" }, 1000 )
    .animate({ borderLeftWidth: "15px" }, 1000 );
});
 
$( "#go3" ).on( "click", function() {
  $( "#go1" ).add( "#go2" ).trigger( "click" );
});
 
$( "#go4" ).on( "click", function() {
  $( "div" ).css({
    width: "",
    fontSize: "",
    borderWidth: ""
  });
});
</script>
 
</body>
</html>

				
			

	

演示

示例 4

动画第一个 div 的 left 属性并同步其余 div，使用步进函数在动画的每个阶段设置它们的 left 属性。

	
		
				
				
				
				
					<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>animate demo</title>
  <style>
  div {
    position: relative;
    background-color: #abc;
    width: 40px;
    height: 40px;
    float: left;
    margin: 5px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-4.0.0.js"></script>
</head>
<body>
 
<p><button id="go">Run »</button></p>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
 
<script>
$( "#go" ).on( "click", function() {
  $( ".block" ).first().animate({
    left: 100
  }, {
    duration: 1000,
    step: function( now, fx ){
      $( ".block" ).slice( 1 ).css( "left", now );
    }
  });
});
</script>
 
</body>
</html>

				
			

	

演示

示例 5

动画所有段落以切换高度和不透明度，在 600 毫秒内完成动画。

	
					$( "p" ).animate({
  height: "toggle",
  opacity: "toggle"
}, "slow" );

示例 6

动画所有段落到 left 样式为 50 且不透明度为 1（不透明，可见），在 500 毫秒内完成动画。

	
					$( "p" ).animate({
  left: 50,
  opacity: 1
}, 500 );

示例 7

动画所有段落的 left 和 opacity 样式属性；在队列外部运行动画，以便它将自动开始而无需等待轮到它。

	
					$( "p" ).animate({
  left: "50px",
  opacity: 1
}, {
  duration: 500,
  queue: false
});

示例 8

使用“缓动”函数提供不同动画风格的示例。这仅在你拥有提供此缓动函数的插件时才有效。请注意，除非段落元素隐藏，否则此代码将不执行任何操作。

	
					$( "p" ).animate({
  opacity: "show"
}, "slow", "easein" );

示例 9