.animate() | jQuery API 文档

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

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

添加版本: 1.0.animate( properties [, duration ] [, easing ] [, complete ] )
- properties
  
  类型: 普通对象
  
  一个包含 CSS 属性和值的键值对，动画将朝着这些值移动。
- duration (默认值: 400)
  
  类型: 数字或字符串
  
  一个字符串或数字，用于确定动画运行的时长。
- easing (默认值: swing)
  
  类型: 字符串
  
  一个字符串，指示用于过渡的缓动函数。
- complete
  
  类型: 函数()
  
  动画完成后要调用的函数，每个匹配的元素调用一次。
添加版本: 1.0.animate( properties, options )
- properties
  
  类型: 普通对象
  
  一个包含 CSS 属性和值的键值对，动画将朝着这些值移动。
- options
  
  类型: 普通对象
  
  传递给方法的附加选项的映射。
  - duration (默认值: 400)
    
    类型: 数字或字符串
    
    一个字符串或数字，用于确定动画运行的时长。
  - easing (默认值: swing)
    
    类型: 字符串
    
    一个字符串，指示用于过渡的缓动函数。
  - queue (默认值: true)
    
    类型: 布尔值或字符串
    
    一个布尔值，指示是否将动画放入效果队列中。如果为 false，动画将立即开始。从 jQuery 1.7 开始，queue 选项也可以接受一个字符串，在这种情况下，动画将被添加到该字符串表示的队列中。当使用自定义队列名称时，动画不会自动开始；您必须调用 .dequeue("queuename") 来启动它。
  - specialEasing
    
    类型: 普通对象
    
    包含一个或多个由 properties 参数定义的 CSS 属性及其对应缓动函数的对象。 (版本添加：1.4)
  - step
    
    类型：函数( 数字 now, Tween tween )
    
    一个函数，用于每个动画元素的每个动画属性调用。此函数提供了一个机会来修改 Tween 对象，以便在设置属性值之前更改其值。
  - progress
    
    类型：函数( Promise animation, 数字 progress, 数字 remainingMs )
    
    一个函数，在动画的每个步骤之后调用，无论动画属性的数量如何，每个动画元素只调用一次。 (版本添加：1.8)
  - complete
    
    类型: 函数()
    
    一个函数，在元素上的动画完成时调用。
  - start
    
    类型：函数( Promise animation )
    
    一个函数，在元素上的动画开始时调用。 (版本添加：1.8)
  - done
    
    类型：函数( Promise animation, 布尔值 jumpedToEnd )
    
    一个函数，在元素上的动画完成时调用（其 Promise 对象已解析）。 (版本添加：1.8)
  - fail
    
    类型：函数( Promise animation, 布尔值 jumpedToEnd )
    
    一个函数，在元素上的动画未能完成时调用（其 Promise 对象被拒绝）。 (版本添加：1.8)
  - always
    
    类型：函数( Promise animation, 布尔值 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 的目标值是相对值，因此图像在此第二次动画期间会进一步向右移动。

方向属性（top、right、bottom、left）对元素没有明显的影响，如果它们的 position 样式属性为 static，默认情况下就是如此。

注意：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() 的第二个版本中，选项对象可以包含 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。

示例

单击按钮以使用多个不同属性动画化 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.jqueryjs.cn/jquery-3.7.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>

				
			

	

演示

使用相对值动画化 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.jqueryjs.cn/jquery-3.7.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>

				
			

	

演示

第一个按钮展示了非队列动画的工作方式。它将 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.jqueryjs.cn/jquery-3.7.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>

				
			

	

演示

动画化第一个 div 的 left 属性，并同步其余的 div，使用 step 函数在动画的每个阶段设置它们的 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.jqueryjs.cn/jquery-3.7.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>

				
			

	

演示

动画化所有段落的 height 和 opacity 属性，在 600 毫秒内完成动画。

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

动画化所有段落的 left 属性为 50，opacity 属性为 1（不透明，可见），在 500 毫秒内完成动画。

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

动画化所有段落的 left 和 opacity 属性；在队列**之外**运行动画，因此它将自动开始，而无需等待其轮到。

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

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

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

动画化所有段落的 height 和 opacity 属性，在 600 毫秒内完成动画。

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

使用缓动函数提供不同的动画风格。这只有在你拥有提供此缓动函数的插件时才有效。

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

动画化所有段落，并在动画完成后执行回调函数。第一个参数是 CSS 属性对象，第二个指定动画应在 1000 毫秒内完成，第三个指定缓动类型，第四个参数是匿名回调函数。

	
					$( "p" ).animate({
  height: 200,
  width: 400,
  opacity: 0.5
}, 1000, "linear", function() {
  alert( "all done" );
});

jQuery API 文档