عرض مصدر jQuery/add

<noinclude>{{DISPLAYTITLE:التابع <code>.add()‎‎‎‎</code>‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في jQuery}}</noinclude>

== <code>‎.add( selector )‎</code> ==

=== القيمة المعادة ===
يُعيد كائنًا من النوع [[jQuery/jQuery|jQuery]].

=== الوصف ===
إنشاء كائن jQuery جديد من العناصر المضافة إلى مجموعة من العناصر المطابقة.

=== <code>add( selector )‎</code> ===
أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.0 1.0].

==== <code>selector</code> ====
سلسلة من النوع [[jQuery/Selector|Selector]] تمثل تعبير مُحدِّد للعثور على عناصر إضافية لإضافتها إلى مجموعة العناصر المطابقة.

=== <code>‎.add( elements )‎</code> ===
أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.0 1.0].

==== <code>elements</code> ====
عنصر واحد أو أكثر من النوع [[JavaScript/Element|Element]] لإضافته إلى مجموعة العناصر المطابقة.

=== <code>‎.add( html )‎</code> ===
أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.0 1.0].

==== <code>html</code> ====
جزء من شيفرة HTML لإضافته إلى مجموعة العناصر المطابقة وهو من النوع <code>[[JavaScript/String|String]]</code>.

=== <code>‎.add( selection )‎</code> ===
أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.3.2 1.3.2].

==== <code>selection</code> ====
كائن موجود من النوع [[jQuery/jQuery|jQuery]] لإضافته إلى مجموعة العناصر المطابقة.

=== <code>‎.add( selector, context )‎</code> ===
أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.4 1.4].

==== <code>selector</code> ====
سلسلة من النوع [[jQuery/Selector|Selector]] تمثل تعبير مُحدِّد للعثور على عناصر إضافية لإضافتها إلى مجموعة العناصر المطابقة.

==== <code>context</code> ====
النقطة في المستند التي يجب أن يبدأ عندها المُحدِّد في المطابقة؛ وهي مشابهة لوسيط السياق الخاص بالتابع ‎<code>$(selector, context)</code>‎ وهو من النوع [[jQuery/Element|Element]].

ولما كان كائن jQuery يمثل مجموعة من عناصر DOM، يقوم التابع ‎<code>.add()‎‎</code> بإنشاء كائن jQuery جديد من اتحاد تلك العناصر وتلك التي مُرِرت إلى التابع. إلى حد كبير، يمكن أن يكون الوسيط المُدخل إلى التابع <code>‎.add()‎‎</code> أي شيء يقبله ‎<code>$()</code>‎‎، بما في ذلك تعبير مُحدِّد jQuery، أو مراجع لعناصر DOM، أو مقتطف من شيفرة HTML.

لا تفترض أن يُلحق هذا التابع العناصرَ إلى المجموعة الموجودة بالترتيب الذي مُرِرت به إلى التابع <code>‎.add()</code>‎‎. عندما تكون كافة العناصر أعضاء في نفس المستند، ستترتب المجموعة الناتجة من التابع <code>‎.add()‎‎</code> بترتيب المستند؛ أي حسب ظهور كل عنصر في المستند. إذا كانت المجموعة تتكون من عناصر من مستندات مختلفة أو من عناصر غير الموجودة في أي مستند، فإن الترتيب يكون غير محدد.

لإنشاء كائن jQuery بعناصر مُرتَبة بترتيب مُعرّف بشكل جيد وبدون حٍمل عملية الترتيب يستخدم الشكل <code>‎$(array_of_DOM_elements)</code>‎.

يمكن استخدام المجموعة المحدّثة من العناصر في تابع متتالي (متسلسل)، أو تعيينها لمتغير لاستخدامه لاحقًا. ومثال على ذلك:<syntaxhighlight lang="jquery">
$( "p" ).add( "div" ).addClass( "widget" );
var pdiv = $( "p" ).add( "div" );
</syntaxhighlight>التالي لن يحفظ العناصر المضافة، لأن التابع ‎<code>.add()‎‎</code> ينشيء مجموعة جديدة ويترك المجموعة الأصلية في <code>pdiv</code> دون تغيير:<syntaxhighlight lang="jquery">
var pdiv = $( "p" );
pdiv.add( "div" ); // خطأ، pdiv لن يتغير
</syntaxhighlight>الصفحة التالية تحتوي على قائمة بسيطة ثم فقرة تليها:<syntaxhighlight lang="html">
<ul>
  <li>البند رقم 1</li>
  <li>البند رقم 2</li>
  <li>البند رقم 3</li>
</ul>
<p>فقرة</p>
</syntaxhighlight>يمكننا تحديد عناصر القائمة ثم الفقرة باستخدام إما محدد أو مرجع لعنصر DOM نفسه كوسيط للتابع <code>‎.add()‎‎</code>:<syntaxhighlight lang="jquery">
$( "li" ).add( "p" ).css( "background-color", "red" );
</syntaxhighlight>أو<syntaxhighlight lang="jquery">
$( "li" ).add( document.getElementsByTagName( "p" )[ 0 ] )
  .css( "background-color", "red" );
</syntaxhighlight>ينتج عن هذا الاستدعاء خلفية حمراء خلف جميع العناصر الأربعة. باستخدام مقتطف HTML كوسيط للتابع <code>‎.add()</code>‎‎ (كما هو الحال في الإصدار الثالثة)، يمكننا إنشاء عناصر إضافية مباشرةً وإضافة تلك العناصر إلى مجموعة العناصر المطابقة. لنفترض على سبيل المثال أننا نريد تغيير خلفية عناصر القائمة إلى جانب فقرة أُنشأت حديثًا:

على الرغم من إنشاء الفقرة الجديدة وتغيير لون خلفيتها، إلا أنها لا تظهر في الصفحة. لوضعها على الصفحة، يمكننا إضافة أحد توابع الإدراج إلى السلسلة.

اعتبارًا من jQuery 1.4 ستُعاد دوماً نتائج التابع ‎<code>.add()</code>‎‎‎ في ترتيب المستند (بدلاً من تسلسل بسيط).

ملاحظة: لعكس تأثير التابع <code>‎.add()‎‎</code> يمكنك استخدام التابع <code>‎.not( elements | selector )</code>‎ لإزالة عناصر من نتائج jQuery أو التابع <code>‎.end()</code>‎‎ للعودة إلى التحديد قبل إضافتك.

== أمثلة ==
العثور على جميع عناصر<code><nowiki><div></nowiki></code> وعمل إطار. ثم إضافة كل الفقرات إلى كائن jQuery لضبط خلفياتها إلى اللون الأصفر.<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add مثال على التابع</title>
  <style>
  div {
    width: 60px;
    height: 60px;
    margin: 10px;
    float: left;
  }
  p {
    clear: left;
    font-weight: bold;
    font-size: 16px;
    color: blue;
    margin: 0 10px;
    padding: 2px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>
 
<p>هذه الفقرة أضيفت ... (لاحظ أنها بلا إطار)</p>
 
<script>
$( "div" ).css( "border", "2px solid red" )
  .add( "p" )
  .css( "background", "yellow" );
</script>
 
</body>
</html>
</syntaxhighlight>إضافة المزيد من العناصر، المُطابِقة لتعبيرٍ محدد، إلى مجموعة العناصر المطابقة.<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add مثال على التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا</p>
<span>مرحبًا مرة أخرى</span>
 
<script>
$( "p" ).add( "span" ).css( "background", "yellow" );
</script>
 
</body>
</html>
</syntaxhighlight>إضافة المزيد من العناصر، التي أُنشأت مباشرة، إلى مجموعة العناصر المُطابقة.<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add مثال على التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا</p>
 
<script>
$( "p" ).clone().add( "<span>مرة أخرى</span>" ).appendTo( document.body );
</script>
 
</body>
</html>
</syntaxhighlight>إضافة عنصر أو أكثر إلى مجموعة العناصر المُطابقة.<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>add مثال على التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا</p>
<span id="a">مرحبًا مرة أخرى</span>
 
<script>
$( "p" ).add( document.getElementById( "a" ) ).css( "background", "yellow" );
</script>
 
</body>
</html>
</syntaxhighlight>يوضح كيفية إضافة (أو دفع) عناصر إلى مجموعة موجودة.

== مصادر ==
* [http://api.jquery.com/add/ صفحة التابع ‎ ‎.add()‎‎‎‎‎في توثيق jQuery الرسمي].
[[تصنيف:jQuery]]
[[تصنيف:jQuery Method]]
[[تصنيف:jQuery Traversing]]