التابع .add() في jQuery
.add( selector )
القيمة المعادة
يُعيد كائنًا من النوع jQuery.
الوصف
إنشاء كائن jQuery جديد من العناصر المضافة إلى مجموعة من العناصر المطابقة.
add( selector )
أُضيف مع الإصدار: 1.0.
selector
سلسلة من النوع Selector تمثل تعبير مُحدِّد للعثور على عناصر إضافية لإضافتها إلى مجموعة العناصر المطابقة.
.add( elements )
أُضيف مع الإصدار: 1.0.
elements
عنصر واحد أو أكثر من النوع Element لإضافته إلى مجموعة العناصر المطابقة.
.add( html )
أُضيف مع الإصدار: 1.0.
html
جزء من شيفرة HTML لإضافته إلى مجموعة العناصر المطابقة وهو من النوع String.
.add( selection )
أُضيف مع الإصدار: 1.3.2.
selection
كائن موجود من النوع jQuery لإضافته إلى مجموعة العناصر المطابقة.
.add( selector, context )
أُضيف مع الإصدار: 1.4.
selector
سلسلة من النوع Selector تمثل تعبير مُحدِّد للعثور على عناصر إضافية لإضافتها إلى مجموعة العناصر المطابقة.
context
النقطة في المستند التي يجب أن يبدأ عندها المُحدِّد في المطابقة؛ وهي مشابهة لوسيط السياق الخاص بالتابع $(selector, context) وهو من النوع Element.
ولما كان كائن jQuery يمثل مجموعة من عناصر DOM، ينُشِئ التابع .add() كائن jQuery جديد من اتحاد تلك العناصر وتلك التي مُرِرت إلى التابع. إلى حد كبير، يمكن أن يكون الوسيط المُدخل إلى التابع .add() أي شيء يقبله $()، بما في ذلك تعبير مُحدِّد jQuery، أو مراجع لعناصر DOM، أو مقتطف من شيفرة HTML.
لا تفترض أن يُلحق هذا التابع العناصرَ إلى المجموعة الموجودة بالترتيب الذي مُرِرت به إلى التابع .add(). عندما تكون كافة العناصر أعضاء في نفس المستند، ستترتب المجموعة الناتجة من التابع .add() بترتيب المستند؛ أي حسب ظهور كل عنصر في المستند. إذا كانت المجموعة تتكون من عناصر من مستندات مختلفة أو من عناصر غير الموجودة في أي مستند، فإن الترتيب يكون غير محدد.
لإنشاء كائن jQuery بعناصر مُرتَبة بترتيب مُعرّف بشكل جيد وبدون حٍمل عملية الترتيب يستخدم الشكل $(array_of_DOM_elements).
يمكن استخدام المجموعة المحدّثة من العناصر في سلسلة (chain)، أو تعيينها لمتغير لاستخدامه لاحقًا. ومثال على ذلك:
$( "p" ).add( "div" ).addClass( "widget" );
var pdiv = $( "p" ).add( "div" );
التالي لن يحفظ العناصر المضافة، لأن التابع .add() ينشيء مجموعة جديدة ويترك المجموعة الأصلية في pdiv دون تغيير:
var pdiv = $( "p" );
pdiv.add( "div" ); // خطأ، pdiv لن يتغير
الصفحة التالية تحتوي على قائمة <ul> بسيطة ثم فقرة <p> تليها:
<ul>
<li>البند رقم 1</li>
<li>البند رقم 2</li>
<li>البند رقم 3</li>
</ul>
<p>فقرة</p>
يمكننا تحديد عناصر القائمة ثم الفقرة باستخدام إما محدد أو مرجع لعنصر DOM نفسه كوسيط للتابع .add():
$( "li" ).add( "p" ).css( "background-color", "red" );
أو:
$( "li" ).add( document.getElementsByTagName( "p" )[ 0 ] )
.css( "background-color", "red" );
ينتج عن هذا الاستدعاء ضبط خلفية حمراء خلف جميع العناصر الأربعة. باستخدام مقتطف HTML كوسيط للتابع .add() (كما هو الحال في الإصدار الثالثة)، يمكننا إنشاء عناصر إضافية مباشرةً وإضافة تلك العناصر إلى مجموعة العناصر المطابقة.
على الرغم من إنشاء الفقرة الجديدة وتغيير لون خلفيتها، إلا أنها لا تظهر في الصفحة. لوضعها على الصفحة، يمكننا إضافة أحد توابع الإدراج إلى السلسلة.
بدءًا من jQuery 1.4 ستُعاد دوماً نتائج التابع .add() في ترتيب المستند (بدلاً من تسلسل بسيط).
ملاحظة: لعكس تأثير التابع .add() يمكنك استخدام التابع .not( elements | selector ) لإزالة عناصر من نتائج jQuery أو التابع .end() للعودة إلى التحديد قبل إضافتك.
أمثلة
العثور على جميع عناصر <div> وعمل إطار. ثم إضافة كل الفقرات إلى كائن jQuery لضبط خلفياتها إلى اللون الأصفر:
<!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>
إضافة المزيد من العناصر، المُطابِقة لتعبيرٍ محدد، إلى مجموعة العناصر المطابقة:
<!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>
إضافة المزيد من العناصر، التي أُنشأت مباشرة، إلى مجموعة العناصر المُطابقة:
<!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>
إضافة عنصر أو أكثر إلى مجموعة العناصر المُطابقة:
<!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>
يوضح كيفية إضافة (أو دفع) عناصر إلى مجموعة موجودة:
<!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>
var collection = $( "p" );
collection = collection.add( document.getElementById( "a" ) );
collection.css( "background", "yellow" );
</script>
</body>
</html>