.slideToggle()

類別： 效果 > 滑動

.slideToggle( [duration ] [, complete ] )傳回： jQuery

說明： 使用滑動動作顯示或隱藏相符的元素。

  • 新增版本： 1.0.slideToggle( [duration ] [, complete ] )

    • duration (預設：400)
      類型： 數字 或 字串
      決定動畫執行時間的字串或數字。
    • complete
      類型： 函式()
      動畫完成後呼叫的函式，每個相符的元素呼叫一次。

  • 新增版本： 1.0.slideToggle( options )

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

  • 新增版本：1.4.3.slideToggle( [duration ] [, easing ] [, complete ] )

    • duration (預設：400)
      類型： 數字 或 字串
      決定動畫執行時間的字串或數字。
    • easing (預設：swing)
      類型：字串
      一個字串，表示在轉場中要使用的緩衝函數。
    • complete
      類型： 函式()
      動畫完成後呼叫的函式，每個相符的元素呼叫一次。

.slideToggle() 方法會對符合的元素高度進行動畫。這會導致頁面的下半部向上或向下滑動，顯示或隱藏項目。如果元素最初顯示，它將被隱藏；如果隱藏，它將被顯示。display 屬性會根據需要儲存和還原。如果元素的 display 值為 inline，然後被隱藏和顯示，它將再次顯示為 inline。當高度在隱藏動畫後達到 0 時，display 樣式屬性會設定為 none，以確保元素不再影響頁面的配置。

持續時間以毫秒為單位；較高的值表示較慢的動畫，而不是較快的動畫。字串 'fast' 和 'slow' 可用於分別表示 200 和 600 毫秒的持續時間。

我們可以為任何元素設定動畫，例如一個簡單的圖片

1
2
3
4
 
<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123">

當另一個元素被按一下時，我們將導致呼叫 .slideToggle()

1
2
3
4
5
 
$( "#clickme" ).on( "click", function() {
  $( "#book" ).slideToggle( "slow", function() {
    // Animation complete.
  });
});

在元素最初顯示時，我們可以在第一次按一下時慢慢隱藏它

圖 1 - 隱藏圖片時 slideToggle() 效果的說明

第二次按一下將再次顯示元素

圖 2 - 顯示圖片時 slideToggle() 效果的說明

緩衝

自 jQuery 1.4.3 起，可以使用命名緩衝函數的選用字串。緩衝函數指定動畫在動畫中不同點進展的速度。jQuery 函式庫中唯一的緩衝實作是預設值，稱為 swing，以及一個以恆定速度進展的實作，稱為 linear。可以使用外掛程式取得更多緩衝函數，最著名的是 jQuery UI 套件。

回呼函數

如果提供，則在動畫完成後會觸發回呼。這對於將不同的動畫依序串接起來很有用。回呼不會傳送任何引數，但 this 會設定為正在執行動畫的 DOM 元素。如果動畫有多個元素，請務必注意，回呼會針對每個符合的元素執行一次，而不是針對整個動畫執行一次。

自 jQuery 1.6 起，.promise() 方法可與 deferred.done() 方法結合使用，以便在 所有 符合的元素完成其動畫時，為整個動畫執行單一回呼（請參閱 .promise() 的範例）。

其他注意事項

  • 所有 jQuery 效果，包含 .slideToggle()，都可以透過設定 jQuery.fx.off = true 全域關閉，這會將持續時間有效設定為 0。更多資訊，請參閱 jQuery.fx.off。
  • 如果對無序清單 (<ul>) 呼叫 .slideDown()，且其 <li> 元素具有位置 (相對、絕對或固定)，則在 IE6 到至少 IE9 中，此效果可能無法正常運作，除非 <ul> 具有「配置」。若要解決此問題，請將 position: relative; 和 zoom: 1; CSS 宣告新增至 ul。

範例

動畫所有段落向上或向下滑動，在 600 毫秒內完成動畫。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slideToggle demo</title>
  <style>
  p {
    width: 400px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<button>Toggle</button>
<p>
  This is the paragraph to end all paragraphs.  You
  should feel <em>lucky</em> to have seen such a paragraph in
  your life.  Congratulations!
</p>
 
<script>
$( "button" ).on( "click", function() {
  $( "p" ).slideToggle( "slow" );
});
</script>
 
</body>
</html>

示範

使用切換動畫區隔線之間的 div，讓一些出現，一些消失。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slideToggle demo</title>
  <style>
  div {
    background: #b977d1;
    margin: 3px;
    width: 60px;
    height: 60px;
    float: left;
  }
  div.still {
    background: #345;
    width: 5px;
  }
  div.hider {
    display: none;
  }
  span {
    color: red;
  }
  p {
    clear: left;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<div></div>
<div class="still"></div>
<div style="display:none;">
</div><div class="still"></div>
<div></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div></div>
<p><button id="aa">Toggle</button> There have been <span>0</span> toggled divs.</p>
 
<script>
$( "#aa" ).on( "click", function() {
  $( "div:not(.still)" ).slideToggle( "slow", function() {
    var n = parseInt( $( "span" ).text(), 10 );
    $( "span" ).text( n + 1 );
  });
});
</script>
 
</body>
</html>

示範