forked from jquery/api.jquery.com
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathclone.xml
108 lines (107 loc) · 5.76 KB
/
clone.xml
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
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
<?xml version="1.0"?>
<entry type="method" name="clone" return="jQuery">
<title>.clone()</title>
<signature>
<added>1.0</added>
<argument name="withDataAndEvents" optional="true" type="Boolean" default="false">
<desc>A Boolean indicating whether event handlers should be copied along with the elements. As of jQuery 1.4, element data will be copied as well.</desc>
</argument>
</signature>
<signature>
<added>1.5</added>
<argument name="withDataAndEvents" optional="true" type="Boolean" default="false">
<desc>A Boolean indicating whether event handlers and data should be copied along with the elements. The default value is <code>false</code>. <em>*In jQuery 1.5.0 the default value was incorrectly <code>true</code>; it was changed back to <code>false</code> in 1.5.1 and up.</em></desc>
</argument>
<argument name="deepWithDataAndEvents" optional="true" type="Boolean" default="value of withDataAndEvents">
<desc>A Boolean indicating whether event handlers and data for all children of the cloned element should be copied. By default its value matches the first argument's value (which defaults to <code>false</code>).</desc>
</argument>
</signature>
<desc>Create a deep copy of the set of matched elements.</desc>
<longdesc>
<p>The <code>.clone()</code> method performs a <em>deep</em> copy of the set of matched elements, meaning that it copies the matched elements as well as all of their descendant elements and text nodes. When used in conjunction with one of the insertion methods, <code>.clone()</code> is a convenient way to duplicate elements on a page. Consider the following HTML:</p>
<pre><code><div class="container">
<div class="hello">Hello</div>
<div class="goodbye">Goodbye</div>
</div></code></pre>
<p>As shown in the discussion for <code><a href="http://api.jquery.com/append/">.append()</a></code>, normally when an element is inserted somewhere in the DOM, it is moved from its old location. So, given the code:</p>
<pre><code>$('.hello').appendTo('.goodbye');</code></pre>
<p>The resulting DOM structure would be:</p>
<pre><code><div class="container">
<div class="goodbye">
Goodbye
<div class="hello">Hello</div>
</div>
</div></code></pre>
<p>To prevent this and instead create a copy of the element, you could write the following:</p>
<pre><code>$('.hello').clone().appendTo('.goodbye');</code></pre>
<p>This would produce:</p>
<pre><code><div class="container">
<div class="hello">Hello</div>
<div class="goodbye">
Goodbye
<div class="hello">Hello</div>
</div>
</div></code></pre>
<blockquote>
<p><strong>Note:</strong> When using the <code>.clone()</code> method, you can modify the cloned elements or their contents before (re-)inserting them into the document.</p>
</blockquote>
<p>Normally, any event handlers bound to the original element are <em>not</em> copied to the clone. The optional <code>withDataAndEvents</code> parameter allows us to change this behavior, and to instead make copies of all of the event handlers as well, bound to the new copy of the element. As of jQuery 1.4, all element data (attached by the <code>.data()</code> method) is also copied to the new copy. </p>
<p>However, objects and arrays within element data are not copied and will continue to be shared between the cloned element and the original element. To deep copy all data, copy each one manually:</p>
<pre><code>var $elem = $('#elem').data( "arr": [ 1 ] ), // Original element with attached data
$clone = $elem.clone( true )
.data( "arr", $.extend( [], $elem.data("arr") ) ); // Deep copy to prevent data sharing
</code></pre>
<p>As of jQuery 1.5, <code>withDataAndEvents</code> can be optionally enhanced with <code>deepWithDataAndEvents </code> to copy the events and data for all children of the cloned element.</p>
<blockquote>
<p><strong>Note:</strong> Using <code>.clone()</code> has the side-effect of producing elements with duplicate <code>id</code> attributes, which are supposed to be unique. Where possible, it is recommended to avoid cloning elements with this attribute or using <code>class</code> attributes as identifiers instead.</p>
</blockquote>
</longdesc>
<example>
<desc>Clones all b elements (and selects the clones) and prepends them to all paragraphs.</desc>
<code><![CDATA[
$("b").clone().prependTo("p");
]]></code>
<html><![CDATA[
<b>Hello</b><p>, how are you?</p>
]]></html>
</example>
<example>
<desc>When using <code>.clone()</code> to clone a collection of elements that are not attached to the DOM, their order when inserted into the DOM is not guaranteed. However, it may be possible to preserve sort order with a workaround, as demonstrated:</desc>
<css><![CDATA[
#orig, #copy, #copy-correct {
float: left;
width: 20%;
}
]]></css>
<code><![CDATA[
// sort order is not guaranteed here and may vary with browser
$('#copy').append($('#orig .elem')
.clone()
.children('a')
.prepend('foo - ')
.parent()
.clone());
// correct way to approach where order is maintained
$('#copy-correct')
.append($('#orig .elem')
.clone()
.children('a')
.prepend('bar - ')
.end());
]]></code>
<html><![CDATA[
<div id="orig">
<div class="elem"><a>1</a></div>
<div class="elem"><a>2</a></div>
<div class="elem"><a>3</a></div>
<div class="elem"><a>4</a></div>
<div class="elem"><a>5</a></div>
</div>
<div id="copy"></div>
<div id="copy-correct"></div>
]]></html>
</example>
<category slug="manipulation/copying"/>
<category slug="version/1.0"/>
<category slug="version/1.5"/>
</entry>