الفرق بين المراجعتين لصفحة: «jQuery/clone»

من موسوعة حسوب
→ التعديل السابق
مرئينص الويكي
لا ملخص تعديل
ط استبدال النص - 'JQuery' ب'jQuery'
 
(8 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة)
سطر 2: سطر 2:
<noinclude>{{DISPLAYTITLE:التابع <code>‎‎.clone()‎</code>‎ في jQuery}}</noinclude>
<noinclude>{{DISPLAYTITLE:التابع <code>‎‎.clone()‎</code>‎ في jQuery}}</noinclude>
===القيمة المعادة===
===القيمة المعادة===
كائن [[JQuery/jQuery|jQuery]].
كائن [[jQuery/jQuery|jQuery]].
===الوصف===
===الوصف===
يُستخدَم التابع <code>‎.clone()</code>‎ في إنشاء نسخة عميقة (deep copy) من مجموعة العناصر المُطابِقة.
يُستخدَم التابع <code>‎.clone()</code>‎ في إنشاء نسخة عميقة (deep copy) من مجموعة العناصر المُطابِقة.
سطر 18: سطر 18:
[[JavaScript/Boolean|قيمة منطقيّة (Boolean)]]، وتُشير ما إذا كان يجب نسخ مُعالِجات الأحداث مع العناصر. القيمة الافتراضيّة هي <code>false</code>.
[[JavaScript/Boolean|قيمة منطقيّة (Boolean)]]، وتُشير ما إذا كان يجب نسخ مُعالِجات الأحداث مع العناصر. القيمة الافتراضيّة هي <code>false</code>.


<nowiki>*</nowiki>في إصدار jQuery 1.5.0 كانت القيمة الافتراضيّة هي <code>true</code> عن طريق الخطأ، وأُعيد تغييرها إلى <code>false</code> في الإصدار 1.5.1 فما فوق.
ملاحظة: في إصدار jQuery 1.5.0 كانت القيمة الافتراضيّة هي <code>true</code> عن طريق الخطأ، وأُعيد تغييرها إلى <code>false</code> في الإصدار 1.5.1 فما فوق.


==== <code>deepWithDataAndEvents</code> (القيمة الافتراضية: قيمة الوسيط <code>withDataAndEvents</code>) ====
==== <code>deepWithDataAndEvents</code> (القيمة الافتراضية: قيمة الوسيط <code>withDataAndEvents</code>) ====
سطر 25: سطر 25:
يُنجِز التّابع ‎<code>.clone()‎</code> نسخة عميقة من مجموعة العناصر المُطابِقة، أي أنّه ينسخ العناصر المُطابِقة بالإضافة إلى العناصر المُنحدِرة عنها والعقد النصيّة.
يُنجِز التّابع ‎<code>.clone()‎</code> نسخة عميقة من مجموعة العناصر المُطابِقة، أي أنّه ينسخ العناصر المُطابِقة بالإضافة إلى العناصر المُنحدِرة عنها والعقد النصيّة.


'''ملاحظة:''' لأسباب تتعلّق بالأداء، لا تُنسَخ الحالة الديناميكيّة لبعض عناصر الحقول (form) (مثل بيانات المستخدم المكتوبة في العنصر ‎<code>[[HTML/textarea|<textarea>]]</code>‎ واختيارات المستخدم في العنصر <code>[[HTML/select|‎<select>]]</code>‎.
'''ملاحظة:''' لأسباب تتعلّق بالأداء، لا تُنسَخ الحالة الديناميكيّة لبعض عناصر الحقول (form) (مثل بيانات المستخدم المكتوبة في العنصر ‎<code>[[HTML/textarea|<textarea>]]</code>‎ واختيارات المستخدم في العنصر <code>[[HTML/select|‎<select>]]</code>‎). عند نسخ العنصر ‎<code>[[HTML/input|<input>]]</code>‎ يُحافَظ على الحالة الديناميكيّة له (مثل بيانات المستخدم المكتوبة في حقول الإدخال النصيّة واختيارات المستخدم في مربّع التأشير) في العناصر المنسوخة.
 
عند مشاركة استخدام التّابع ‎<code>.clone()‎</code> مع أحد توابع الإدخال، يُصبِح طريقة مثاليّة لتكرار العناصر في الصفحة، فلنأخذ المثال التالي:<syntaxhighlight lang="html">
<div class="container">
  <div class="hello">مرحبًا</div>
  <div class="goodbye">وداعًا</div>
</div>
</syntaxhighlight>كما رأينا في توثيق التّابع <code>[[jQuery/append|‎.append()‎]]</code> ، عندما يُدخَل عنصر في مكان من DOM، يُنقَل من مكانه القديم. فعند استخدام الشيفرة التالية:<syntaxhighlight lang="javascript">
$( ".hello" ).appendTo( ".goodbye" );
</syntaxhighlight>تكون بنية DOM الناتجة هي:<syntaxhighlight lang="html">
<div class="container">
  <div class="goodbye">
    وداعًا
    <div class="hello">مرحبًا</div>
  </div>
</div>
</syntaxhighlight>ولمنع حدوث هذا وإنشاء نسخة من العنصر بدلًا من ذلك، نكتب الشيفرة التالية:<syntaxhighlight lang="javascript">
$( ".hello" ).clone().appendTo( ".goodbye" );
</syntaxhighlight>ينتج عن هذه الشيفرة ما يلي:<syntaxhighlight lang="html">
<div class="container">
  <div class="hello">مرحبًا</div>
  <div class="goodbye">
    وداعًا
    <div class="hello">مرحبًا</div>
  </div>
</div>
 
</syntaxhighlight>'''ملاحظة:''' بالإمكان عند استخدام التّابع ‎<code>.clone()</code>‎ تعديل العناصر المنسوخة أو محتوياتها قبل إعادة إدخالها في المستند.
 
لا تُنسَخ مُعالِجات الأحداث المربوطة إلى العنصر الأصلي بشكل اعتيادي. يسمح لنا المُعامِل <code>withDataAndEvents</code> بتغيير هذا السلوك ونسخ جميع مُعالِجات الأحداث أيضًا وربطها إلى نسخة العناصر الجديدة. بدءًا من إصدار jQuery 1.4 أصبحت كافّة بيانات العناصر (المُرفقة عن طريق التّابع <code>‎.data()‎</code>) تُنسَخ إلى نسخة العناصر الجديدة.
 
على الرغم من ذلك لا تُنسَخ المصفوفات والكائنات الموجودة بداخل بيانات العناصر وستستمر مشاركتها بين العناصر المنسوخة والعناصر الأصليّة، ومن أجل النسخ العميق لكافّة البيانات انسخ كل واحدة بمفردها يدويًّا:<syntaxhighlight lang="javascript">
// العناصر الأصلية مع بيانات مرفقة إليها
var $elem = $( "#elem" ).data( "arr", [ 1 ] ),
    $clone = $elem.clone( true )
      // نسخة عميقة لمنع مشاركة البيانات
      .data( "arr", $.extend( [], $elem.data( "arr" ) ) );
 
</syntaxhighlight>بدءًا من إصدار jQuery 1.5، يُمكِن تعزيز الوسيط <code>withDataAndEvents</code> بشكل اختياري بالوسيط <code>deepWithDataAndEvents</code> لنسخ الأحداث والبيانات لكافّة العناصر الأبناء للعناصر المنسوخة.
 
ملاحظة: يمتلك استخدام التّابع <code>‎.clone()‎</code> تأثير جانبي وهو إنتاج عناصر تمتلك خاصيّة <code>id</code> مُكرَّرة، والتي من المفترض أن تكون فريدة. لذا من المفضّل بقدر الإمكان تجنّب نسخ العناصر التي تمتلك هذه الخاصيّة أو استخدام خاصيّة الصّنف <code>class</code> كمُعرِّفات بدلًا من ذلك.
 
=== أمثلة ===
نسخ كافّة عناصر <code>[[HTML/b|<nowiki><b></nowiki>]]</code> (وتحديد النُسَخ) وإرفاقها قبل كافّة الفقرات:<syntaxhighlight lang="html">
<!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>
</syntaxhighlight>
 
==<span>مصادر</span>==
*<span>[http://api.jquery.com/clone/ صفحة التابع ‎‎‎‎.clone()‎ في توثيق jQuery الرسمي].</span>
[[تصنيف:jQuery]]
[[تصنيف:jQuery Manipulation]]

المراجعة الحالية بتاريخ 09:21، 24 يونيو 2018

‎.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>

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=jQuery/clone&oldid=11173»