.clone()

Categories: Manipulation > Copying

.clone( [withDataAndEvents] ) Returns: jQuery

説明: マッチした要素集合のディープコピー（深いコピー：オブジェクトそのもののコピー）を作成します。

  • version added: 1.0 .clone( [withDataAndEvents] )

    withDataAndEventsイベントハンドラを、要素と一緒にコピーすべきかどうかを示すブール値。 jQuery 1.4では、要素データもコピーされます。

  • version added: 1.5 .clone( [withDataAndEvents] [, deepWithDataAndEvents] )

    withDataAndEventsイベントハンドラを、要素と一緒にコピーすべきかどうかを示すブール値。 デフォルト値は false です。 *jQuery 1.5.0では、誤ってデフォルト値が true になっていましたが、 1.5.1 以降は、変更されて false へ戻されています。

    deepWithDataAndEventsイベントハンドラとクローン・コピー要素のすべての子のデータをコピーすべきかどうかを示すブール値。デフォルトでは、値は最初の引数の値（デフォルトでは false）に一致します。

.clone() メソッドは、マッチした要素集合の deep（ディープ）コピーを実行します。つまり、要素の全子孫要素とテキストノードのみならず、マッチした要素をコピーすることを意味します。 挿入メソッドのいずれかと組合わせて使用すると、.clone() はページの要素を複製するための便利な方法です。次のHTMLを考えてみましょう:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">Goodbye</div>
</div>

.append() の論議で示したように、通常、要素がDOMのどこかに挿入される場合、元の場所から移動されます。従って、次のコードが与えられたとすると As shown in the discussion for .append(), normally when an element is inserted somewhere in the DOM, it is moved from its old location. So, given the code:

$('.hello').appendTo('.goodbye');

結果、DOM 構造は次のようになります:

<div class="container">
  <div class="goodbye">
    Goodbye
    <div class="hello">Hello</div>
  </div>
</div>

これを回避し、要素のコピーを作成するには、次のように書きます:

$('.hello').clone().appendTo('.goodbye');

次のようになります:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">
    Goodbye
    <div class="hello">Hello</div>
  </div>
</div>

.clone() メソッドを使用する場合、ドキュメントに(再)挿入する前にクローン・コピーの要素または内容を修正することができることに注意してください。

通常は、元の要素にバインドされているイベントハンドラは、クローンにコピーされません。 オプションの withDataAndEvents パラメータは、この動作の変更と、代わりに、 要素の新しいコピーにバインドされているイベントハンドラのすべてのコピーを作ることができます。 jQuery 1.4では、すべての（.data() メソッドによってアタッチされた）要素データも、新しいコピーに複写されます。

ただし、オブジェクトと要素のデータ内の配列はコピーされないため、クローン要素とオリジナル要素間で共有されます。 全データをディープコピーするため、各データを手動でコピーします:

var $elem = $('#elem').data( "arr": [ 1 ] ), // アタッチされたたデータを持つ元の要素
    $clone = $elem.clone( true )
    .data( "arr", $.extend( [], $elem.data("arr") ) ); // データ共有をしないためのディープコピー

jQuery 1.5 での withDataAndEvents は、オプションによりクローン要素における全ての子のイベントやデータをコピーするために、deepWithDataAndEvents で拡張することができます。

例:

例:すべてのb要素をクローンを作成し、（クローンを選択して）全てのパラグラフの前に付加します。 

<!DOCTYPE html>
<html>
<head>
  <script src="/files/jquery.js"></script>
</head>
<body>
  <b>Hello</b><p>, how are you?</p>
<script>
  $("b").clone().prependTo("p");
</script>
</body>
</html>

デモ:

例:DOMにアタッチされていない要素のコレクションのクローンを作るために.clone()を使用する場合、DOMに挿入した時のそれらの順序は保証されません。しかし、デモの通り、この問題の回避策によりソート順を維持することができます: 

<!DOCTYPE html>
<html>
<head>
  <style>
  #orig, #copy, #copy-correct {
    float: left;
    width: 20%;
  }
</style>
  <script src="/files/jquery.js"></script>
</head>
<body>
<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>
<script>
// 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()); 
</script>
</body>
</html>

デモ: