.animate() | jQuery API 文件

.animate( properties [, duration ] [, easing ] [, complete ] )傳回： jQuery

說明： 執行一組 CSS 屬性的自訂動畫。

新增版本： 1.0.animate( properties [, duration ] [, easing ] [, complete ] )
- properties
  
  類型： PlainObject
  
  動畫將朝向的 CSS 屬性和值物件。
- duration (預設：400)
  
  類型： Number 或 String
  
  決定動畫執行時間的字串或數字。
- easing (預設：swing)
  
  類型： String
  
  指示要使用哪個緩動函數進行轉場的字串。
- 完成
  
  類型：函數()
  
  動畫完成後呼叫的函數，每個匹配的元素呼叫一次。
新增版本：1.0.animate( properties, options )
- properties
  
  類型： PlainObject
  
  動畫將朝向的 CSS 屬性和值物件。
- 選項
  
  類型： PlainObject
  
  傳遞給方法的其他選項的對應。
  - duration (預設：400)
    
    類型： Number 或 String
    
    決定動畫執行時間的字串或數字。
  - easing (預設：swing)
    
    類型： String
    
    指示要使用哪個緩動函數進行轉場的字串。
  - 佇列（預設：true）
    
    類型：布林值或字串
    
    一個布林值，表示是否將動畫放入效果佇列。如果為 false，動畫將立即開始。從 jQuery 1.7 開始，佇列選項也可以接受字串，在這種情況下，動畫會加入由該字串表示的佇列。當使用自訂佇列名稱時，動畫不會自動開始；您必須呼叫 .dequeue("queuename") 來啟動它。
  - 特殊緩衝
    
    類型： PlainObject
    
    包含一個或多個由屬性參數定義的 CSS 屬性及其對應緩衝函數的物件。（新增版本：1.4）
  - 步驟
    
    類型：函數( 數字 now, Tween tween )
    
    針對每個動畫元素的每個動畫屬性呼叫的函數。此函數提供修改 Tween 物件的機會，以在設定屬性值之前變更其值。
  - 進度
    
    類型：函數( 承諾 animation, 數字 progress, 數字 remainingMs )
    
    在動畫的每個步驟後呼叫的函數，每個動畫元素只呼叫一次，不論動畫屬性的數量。（新增版本：1.8）
  - 完成
    
    類型：函數()
    
    元素上的動畫完成後呼叫的函數。
  - 開始
    
    類型：函數( 承諾 animation )
    
    元素上的動畫開始時呼叫的函數。（新增版本：1.8）
  - 完成
    
    類型：函數( 承諾動畫，布林值 jumpedToEnd )
    
    元素上的動畫完成時呼叫的函數（其 Promise 物件已解決）。（版本新增：1.8）
  - 失敗
    
    類型：函數( 承諾動畫，布林值 jumpedToEnd )
    
    元素上的動畫未完成時呼叫的函數（其 Promise 物件已拒絕）。（版本新增：1.8）
  - 始終
    
    類型：函數( 承諾動畫，布林值 jumpedToEnd )
    
    元素上的動畫完成或未完成即停止時呼叫的函數（其 Promise 物件已解決或拒絕）。（版本新增：1.8）

.animate() 方法允許我們在任何數值 CSS 屬性上建立動畫效果。唯一必要的參數是 CSS 屬性的純粹物件。此物件類似於可以傳送至 .css() 方法的物件，但屬性範圍較為嚴格。

動畫屬性和值

所有動畫屬性都應動畫到單一數值，除非如下所述；大多數非數值的屬性無法使用基本的 jQuery 功能進行動畫（例如，width、height 或 left 可以進行動畫，但 background-color 無法進行動畫，除非使用 jQuery.Color 外掛程式）。除非另有說明，否則屬性值會被視為像素數。在適用的情況下，可以指定單位 em 和 %。

除了樣式屬性之外，某些非樣式屬性（例如 scrollTop 和 scrollLeft）以及自訂屬性也可以進行動畫。

簡寫 CSS 屬性（例如字型、背景、邊框）並未完全支援。例如，如果您要對呈現的邊框寬度進行動畫，則至少必須預先設定邊框樣式和非「自動」的邊框寬度。或者，如果您要對字型大小進行動畫，您會使用 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" ).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() 的第二個版本中，選項物件可以包含 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.jquery.com/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.jquery.com/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.jquery.com/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.jquery.com/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>

				
			

	

示範

動畫化所有段落，以切換高度和不透明度，在 600 毫秒內完成動畫。

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

將所有段落動畫化為左邊樣式 50 和不透明度 1（不透明，可見），在 500 毫秒內完成動畫。

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

動畫化所有段落的左邊和不透明度樣式屬性；在佇列外部執行動畫，以便它會自動開始，而不用等待輪到它。

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

使用「緩衝」函數提供不同動畫樣式的範例。這只有在您有提供此緩衝函數的插件時才會運作。請注意，除非段落元素是隱藏的，否則此程式碼不會執行任何動作。

	
					$( "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" );
});

jQuery API 文件