التابع ‎‎.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>