.animate() | jQuery中文网 | jQuery API 中文文档

.animate( properties [, duration ] [, easing ] [, complete ] )返回类型：jQuery

描述：执行一些CSS属性的自定义动画。

增补版本：1.0.animate( properties [, duration ] [, easing ] [, complete ] )
- properties
  
  类型：PlainObject
  
  动画将移动到的CSS属性和值的对象。
- duration (默认值： 400)
  
  类型：Number or String
  
  一个字符串或数字，决定了动画将运行多长时间。
- easing (默认值： swing)
  
  类型：String
  
  一个字符串，指示要对过渡所用的渐进函数。
- complete
  
  类型：Function()
  
  每当动画完成时要调用的函数，针对每个匹配的元素调用一次。
增补版本：1.0.animate( properties, options )
- properties
  
  类型：PlainObject
  
  动画将移动到的CSS属性和值的对象。
- options
  
  类型：PlainObject
  
  要传递给此方法的额外选项的映射。
  - duration (默认值： 400)
    
    类型：Number or String
    
    一个字符串或数字，决定了动画将运行多长时间。
  - easing (默认值： swing)
    
    类型：String
    
    一个字符串，指示要对过渡所用的渐进函数。
  - queue (默认值： true)
    
    类型：Boolean or String
    
    一个布尔值，指示是否要把动画放到效果队列中。如果是false，它会立即开始。自从jQuery 1.7以来，队列选择也可以接受一个字符串，它导致动画可以添加到用字符串表示的队列中。如果队列名所用的动画还没有自动开始，你必须调用.dequeue("queuename")来启动它。
  - specialEasing
    
    类型：PlainObject
    
    一个对象，包含了一个或多个CSS属性，则属性参数和它们对应的渐进函数定义。 (增补版本：1.4)
  - step
    
    类型：Function( Number now, 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和%。

除了样式属性，一些非样式属性，譬如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()方法来取得一个你可以附加回调函数的应答，会对任何数目的变动集合引发一次，包括零元素的集合。

基本用法

若要让某个元素动起来，譬如让一个简单图像动起来：

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

若要同步变动图像的不透明度、左侧偏移以及高度：

$( "#clickme" ).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）在元素上没有可辨识的效果，static是position的默认值。

注意：jQuery UI项目扩展了.animate方法，允许一些非数字的样式，譬如颜色变成可变动的。此项目还包括了用于通过CSS类而不是通过独立的特性来指定动画的机制。

注意：如果尝试用0像素高度和宽度变一个元素，由于overflow，元素的内容是可见的，jQuery可能会在动画过程中剪短overflow。然而，通过把原始元素的尺寸固定为隐藏，就可以确保动画平滑运行。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" ).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" ).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来全局地关闭，它会有效地把duration设置为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.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button id="go">&raquo; Run</button>
<div id="block">Hello!</div>
 
<script>
// Using multiple unit types within one animation.
 
$( "#go" ).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.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button id="left">&laquo;</button>
<button id="right">&raquo;</button>
<div class="block"></div>
 
<script>
$( "#right" ).click(function() {
  $( ".block" ).animate({ "left": "+=50px" }, "slow" );
});
 
$( "#left" ).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.jquery.com/jquery-1.10.2.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" ).click(function() {
  $( "#block1" )
    .animate({
      width: "90%"
    }, {
      queue: false,
      duration: 3000
    })
    .animate({ fontSize: "24px" }, 1500 )
    .animate({ borderRightWidth: "15px" }, 1500 );
});
 
$( "#go2" ).click(function() {
  $( "#block2" )
    .animate({ width: "90%" }, 1000 )
    .animate({ fontSize: "24px" }, 1000 )
    .animate({ borderLeftWidth: "15px" }, 1000 );
});
 
$( "#go3" ).click(function() {
  $( "#go1" ).add( "#go2" ).click();
});
 
$( "#go4" ).click(function() {
  $( "div" ).css({
    width: "",
    fontSize: "",
    borderWidth: ""
  });
});
</script>
 
</body>
</html>

演示：

变动第一个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-1.10.2.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" ).click(function() {
  $( ".block:first" ).animate({
    left: 100
  }, {
    duration: 1000,
    step: function( now, fx ){
      $( ".block:gt(0)" ).css( "left", now );
    }
  });
});
</script>
 
</body>
</html>

演示：

变动所有的段落，以切换高度和不透明度，在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
});

此示例使用“easing”函数来提供不同的动画样式。只有当你拥有提供这些渐变函数的插件的时候，才起作用。请注意，这些代码不做任何事情，除非段落元素是隐藏的。

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

变动所有段落，切换高度和不透明度，在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" );
});