التابع .clone() في jQuery
.clone( [withDataAndEvents ] )
القيمة المعادة
كائن jQuery.
الوصف
يُستخدَم التابع .clone() في إنشاء نسخة عميقة (deep copy) من مجموعة العناصر المُطابِقة.
.clone( [withDataAndEvents ] )
أضيفت في الإصدار: 1.0.
withDataAndEvents (القيمة الافتراضة: false)
قيمة منطقيّة (Boolean)، وتُشير ما إذا كان يجب نسخ مُعالِجات الأحداث مع العناصر. بدءًا من إصدار jQuery 1.4 أصبحت بيانات العنصر تُنسَخ أيضًا.
.clone( [withDataAndEvents ] [, deepWithDataAndEvents ] )
أضيفت في الإصدار: 1.5.
withDataAndEvents (القيمة الافتراضية: false)
قيمة منطقيّة (Boolean)، وتُشير ما إذا كان يجب نسخ مُعالِجات الأحداث مع العناصر. القيمة الافتراضيّة هي false.
ملاحظة: في إصدار jQuery 1.5.0 كانت القيمة الافتراضيّة هي true عن طريق الخطأ، وأُعيد تغييرها إلى false في الإصدار 1.5.1 فما فوق.
deepWithDataAndEvents (القيمة الافتراضية: قيمة الوسيط withDataAndEvents)
قيمة منطقيّة (Boolean)، وتُشير ما إذا كان يجب نسخ مُعالِجات الأحداث مع البيانات لكافّة العناصر الأبناء للعناصر المنسوخة. تكون قيمته الافتراضيّة هي قيمة الوسيط الأول (والتي هي false بشكل افتراضي).
يُنجِز التّابع .clone() نسخة عميقة من مجموعة العناصر المُطابِقة، أي أنّه ينسخ العناصر المُطابِقة بالإضافة إلى العناصر المُنحدِرة عنها والعقد النصيّة.
ملاحظة: لأسباب تتعلّق بالأداء، لا تُنسَخ الحالة الديناميكيّة لبعض عناصر الحقول (form) (مثل بيانات المستخدم المكتوبة في العنصر <textarea> واختيارات المستخدم في العنصر <select>). عند نسخ العنصر <input> يُحافَظ على الحالة الديناميكيّة له (مثل بيانات المستخدم المكتوبة في حقول الإدخال النصيّة واختيارات المستخدم في مربّع التأشير) في العناصر المنسوخة.
عند مشاركة استخدام التّابع .clone() مع أحد توابع الإدخال، يُصبِح طريقة مثاليّة لتكرار العناصر في الصفحة، فلنأخذ المثال التالي:
<div class="container">
<div class="hello">مرحبًا</div>
<div class="goodbye">وداعًا</div>
</div>
كما رأينا في توثيق التّابع .append() ، عندما يُدخَل عنصر في مكان من DOM، يُنقَل من مكانه القديم. فعند استخدام الشيفرة التالية:
$( ".hello" ).appendTo( ".goodbye" );
تكون بنية DOM الناتجة هي:
<div class="container">
<div class="goodbye">
وداعًا
<div class="hello">مرحبًا</div>
</div>
</div>
ولمنع حدوث هذا وإنشاء نسخة من العنصر بدلًا من ذلك، نكتب الشيفرة التالية:
$( ".hello" ).clone().appendTo( ".goodbye" );
ينتج عن هذه الشيفرة ما يلي:
<div class="container">
<div class="hello">مرحبًا</div>
<div class="goodbye">
وداعًا
<div class="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 لنسخ الأحداث والبيانات لكافّة العناصر الأبناء للعناصر المنسوخة.
ملاحظة: يمتلك استخدام التّابع .clone() تأثير جانبي وهو إنتاج عناصر تمتلك خاصيّة id مُكرَّرة، والتي من المفترض أن تكون فريدة. لذا من المفضّل بقدر الإمكان تجنّب نسخ العناصر التي تمتلك هذه الخاصيّة أو استخدام خاصيّة الصّنف class كمُعرِّفات بدلًا من ذلك.
أمثلة
نسخ كافّة عناصر <b> (وتحديد النُسَخ) وإرفاقها قبل كافّة الفقرات:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>clone مثال عن التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<b>مرحبًا</b><p>، كيف حالك؟</p>
<script>
$( "b" ).clone().prependTo( "p" );
</script>
</body>
</html>