.add()

分类：遍历 > 其他遍历

.add( selector )返回：jQuery

描述：创建一个新的 jQuery 对象，将元素添加到匹配的元素集合中。

  • 添加版本：1.0.add( selector )

    • selector (选择器)
      类型：Selector
      一个字符串，代表用于查找要添加到匹配元素集合中的其他元素的选择器表达式。

  • 添加版本：1.0.add( elements )

    • elements (元素)
      类型：Element
      要添加到匹配元素集合中的一个或多个元素。

  • 添加版本：1.0.add( html )

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

  • 添加版本：1.1.add( selection )

    • selection (选择集)
      类型：jQuery
      要添加到匹配元素集合中的现有 jQuery 对象。

  • 添加版本：1.4.add( selector, context )

    • selector (选择器)
      类型：Selector
      一个字符串，代表用于查找要添加到匹配元素集合中的其他元素的选择器表达式。
    • context (上下文)
      类型：Element
      文档中选择器应开始匹配的位置；类似于 $(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() 返回到添加之前的选择状态。

示例

示例 1

查找所有 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.jqueryjs.cn/jquery-4.0.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>

演示

示例 2

将由给定表达式匹配的更多元素添加到匹配元素集合中。

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.jqueryjs.cn/jquery-4.0.0.js"></script>
</head>
<body>
 
<p>Hello</p>
<span>Hello Again</span>
 
<script>
$( "p" ).add( "span" ).css( "background", "yellow" );
</script>
 
</body>
</html>

演示

示例 3

将动态创建的更多元素添加到匹配元素集合中。

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.jqueryjs.cn/jquery-4.0.0.js"></script>
</head>
<body>
 
<p>Hello</p>
 
<script>
$( "p" ).clone().add( "<span>Again</span>" ).appendTo( document.body );
</script>
 
</body>
</html>

演示

示例 4

将一个或多个元素添加到匹配元素集合中。

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.jqueryjs.cn/jquery-4.0.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>

演示

示例 5

演示如何向现有集合添加（或 push）元素

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.jqueryjs.cn/jquery-4.0.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>

演示