.add()

分類：循覽 > 雜項循覽

.add( selector )傳回：jQuery

說明：建立一個新的 jQuery 物件，其中包含新增至已配對元素組的元素。

  • 新增版本：1.0.add( selector )

    • selector
      類型：選擇器
      代表選擇器運算式的字串，用於尋找要新增至已配對元素組的其他元素。

  • 新增版本：1.0.add( elements )

    • elements
      類型：元素
      一個或多個要新增至已配對元素組的元素。

  • 新增版本：1.0.add( html )

    • html
      類型：htmlString
      要加入到匹配元素集合中的 HTML 片段。

  • 新增版本：1.1.add( selection )

    • selection
      類型：jQuery
      現有的 jQuery 物件，要加入到匹配元素集合中。

  • 新增版本：1.4.add( selector, context )

    • selector
      類型：選擇器
      代表選擇器運算式的字串，用於尋找要新增至已配對元素組的其他元素。
    • context
      類型：元素
      文件中的點，選擇器應從此處開始比對；類似於 $(selector, context) 方法的 context 參數。

給定一個表示 DOM 元素集合的 jQuery 物件，.add() 方法會從這些元素與傳入方法中的元素的聯集建立一個新的 jQuery 物件。傳遞給 .add() 的參數可以是 $() 接受的任何內容，包括 jQuery 選擇器表示式、DOM 元素的參考或 HTML 片段。

不要假設此方法會按照傳遞給 .add() 方法的順序將元素附加到現有的集合中。當所有元素都是同一個文件中的成員時，.add() 的結果集合會按照文件順序排序；也就是按照每個元素在文件中的出現順序排序。如果集合包含來自不同文件或不在任何文件中的元素，則排序順序未定義。若要建立一個元素順序明確且沒有排序負擔的 jQuery 物件，請使用 $(array_of_DOM_elements) 簽章。

更新的元素集合可以用在後續的（串連）方法中，或指定給變數以供稍後使用。例如

1
2
 
$( "p" ).add( "div" ).addClass( "widget" );
var pdiv = $( "p" ).add( "div" );

以下內容不會儲存新增的元素，因為 .add() 方法會建立一個新的集合，並讓 pdiv 中的原始集合保持不變

1
2
 
var pdiv = $( "p" );
pdiv.add( "div" ); // WRONG, pdiv will not change

考量一個包含一個簡單清單及後續段落的網頁

1
2
3
4
5
6
 
<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
</ul>
<p>a paragraph</p>

我們可以使用選擇器或對 DOM 元素本身的參考作為 .add() 方法的參數，來選取清單項目，然後選取段落

1
 
$( "li" ).add( "p" ).css( "background-color", "red" );

或

1
2
 
$( "li" ).add( document.getElementsByTagName( "p" )[ 0 ] )
  .css( "background-color", "red" );

此呼叫的結果會在所有四個元素後面加上紅色背景。使用 HTML 片段作為 .add() 方法的參數（就像在第三個版本中），我們可以動態建立其他元素，並將這些元素新增到匹配的元素組。例如，我們想要變更清單項目以及新建立段落的背景

1
2
 
$( "li" ).add( "<p id='new'>new paragraph</p>" )
  .css( "background-color", "red" );

雖然已建立新的段落並變更其背景顏色，但它仍不會顯示在網頁上。若要將其放置在網頁上，我們可以將其中一個插入方法新增到鏈中。

從 jQuery 1.4 開始，.add() 的結果將永遠以文件順序傳回（而非單純的串接）。

注意：若要反轉 .add()，您可以使用 .not( elements | selector ) 從 jQuery 結果中移除元素，或使用 .end() 回到您新增前的選取。

範例

找出所有 div 並建立一個框線。然後將所有段落新增到 jQuery 物件中，以設定其背景為黃色。

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
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add demo</title>
  <style>
  div {
    width: 60px;
    height: 60px;
    margin: 10px;
    float: left;
  }
  p {
    clear: left;
    font-weight: bold;
    font-size: 16px;
    color: blue;
    margin: 0 10px;
    padding: 2px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>
 
<p>Added this... (notice no border)</p>
 
<script>
$( "div" ).css( "border", "2px solid red" )
  .add( "p" )
  .css( "background", "yellow" );
</script>
 
</body>
</html>

示範

將更多由指定表達式匹配的元素新增到匹配的元素組中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add demo</title>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<p>Hello</p>
<span>Hello Again</span>
 
<script>
$( "p" ).add( "span" ).css( "background", "yellow" );
</script>
 
</body>
</html>

示範

將更多動態建立的元素新增到匹配的元素組中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add demo</title>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<p>Hello</p>
 
<script>
$( "p" ).clone().add( "<span>Again</span>" ).appendTo( document.body );
</script>
 
</body>
</html>

示範

將一個或多個元素新增到匹配的元素組中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add demo</title>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<p>Hello</p>
<span id="a">Hello Again</span>
 
<script>
$( "p" ).add( document.getElementById( "a" ) ).css( "background", "yellow" );
</script>
 
</body>
</html>

示範

示範如何將元素新增（或推入）現有的集合中

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add demo</title>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<p>Hello</p>
<span id="a">Hello Again</span>
 
<script>
var collection = $( "p" );
// Capture the new collection
collection = collection.add( document.getElementById( "a" ) );
collection.css( "background", "yellow" );
</script>
 
</body>
</html>

示範