التابع .prepend() في jQuery
.prepend( content [, content ] )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يُستخدَم هذا التابع في إدخال لمحتوى المُحدَّد عن طريق المُعامِل إلى بداية كل عنصر من مجموعة العناصر المُطابِقة.
.prepend( content [, content ] )
أضيف مع الإصدار 1.0.
content
سلسلة نصيّة من الكائن htmlString، أو عنصر، أو نص، أو مصفوفة، أو كائن jQuery، وتُمثِّل سلسلة HTML، أو عنصر DOM، أو عقدة نصيّة (text node)، أو مصفوفة من العناصر والعقد النصيّة، أو كائن jQuery المطلوب إدخالها في بداية كل عنصر من مجموعة العناصر المُطابقة.
content
سلسلة نصيّة من الكائن htmlString، أو عنصر، أو نص، أو مصفوفة، أو كائن jQuery، وتُمثِّل عنصرًا إضافيًا واحدًا أو أكثر من عناصر DOM، أو العقد النصيّة (text node)، أو مصفوفات من العناصر والعقد النصية، أو سلسلة HTML، أو كائنات jQuery المطلوب إدخالها في بداية كل عنصر من مجموعة العناصر المُطابقة.
.prepend( function )
أضيف مع الإصدار 1.4.
function
دالة على الشكل Function( Integer elementOfArray, String html ) تُعيد سلسلة نصيّة من الكائن htmlString، أو عنصر أو عناصر DOM، أو عقدة أو عقد نصيّة، أو كائن jQuery المطلوب إدخالها في بداية كل عنصر من مجموعة العناصر المُطابقة. تستقبل فهرس موقع العنصر في المجموعة وقيمة HTML القديمة للعنصر كوسائط لها. يُمثِّل المعاملُ this في الدالة العنصرَ الحالي في المجموعة.
يُدخِل التّابع .prepend() المحتوى المُحدَّد كأول ابن (first child) لكل عنصر من مجموعة jQuery (استخدم لإدخاله كآخر ابن التابع .append()).
ينجز التابعان .prepend() و .prependTo() الوظيفة ذاتها ويكمن الفرق الأساسي بينهما في الصّياغة، أي في المحتوى المراد إدخاله والعناصر الهدف التي سيدخل إليها هذا المحتوى. فبالنسبة للتابع .prepend()، يُشير تعبير المُحدِّد (selector) الذي يسبق التّابع إلى الحاوية التي سيُدخَل إليها المحتوى. أما في التّابع ،.prependTo() المحتوى الذي يسبق التابع هو إمّا تعبير مُحدِّد أو عناصر HTML مُنشأة بشكل مباشر، ويُدخَل إلى الحاوية الهدف.
فلنأخذ مثال شيفرة HTML التالية:
<h2>السلام عليكم</h2>
<div class="container">
<div class="inner">مرحبًا</div>
<div class="inner">وداعًا</div>
</div>
بإمكاننا إنشاء المحتوى وإدخاله إلى عناصر متعدّدة بنفس الوقت:
$( ".inner" ).prepend( "<p>تجربة</p>" );
سيحصل كل عنصر <div class="inner"> على المحتوى الجديد:
<h2>السلام عليكم</h2>
<div class="container">
<div class="inner">
<p>تجربة</p>
مرحبًا
</div>
<div class="inner">
<p>تجربة</p>
وداعًا
</div>
</div>
بإمكاننا أيضًا تحديد عنصر من الصفحة وإدخاله إلى عنصر آخر:
$( ".container" ).prepend( $( "h2" ) );
إن أدخلنا عنصرًا مختارًا بهذه الطريقة إلى موقع واحد في أي مكان من DOM، فسينتقل إلى العنصر الهدف (ولن يُنسَخ):
<div class="container">
<h2>السلام عليكم</h2>
<div class="inner">مرحبًا</div>
<div class="inner">وداعًا</div>
</div>
ملاحظة مهمة: إن كان هنالك أكثر من عنصر هدف، فستُنشَأ نسخة من العنصر المُدخَل لكل عنصر هدف ما عدا العنصر الأخير.
وسائط إضافيّة
كما هو الحال مع توابع إضافة المحتوى الأخرى مثل .append() و .before()، يدعم التابع .prepend() تمرير وسائط متعدّدة كمُدخلات. تتضمن المُدخلات المدعومة عناصر DOM، وكائنات jQuery، وسلاسل HTML النصيّة، ومصفوفات من عناصر DOM.
على سبيل المثال، ستدرج الشيفرة التالية عنصري <div> جديدين وعنصر <div> موجود كأول ثلاثة أبناء للعنصر <body>:
var $newdiv1 = $( "<div id='object1'></div>"),
newdiv2 = document.createElement( "div" ),
existingdiv1 = document.getElementById( "foo" );
$( "body" ).prepend( $newdiv1, [ newdiv2, existingdiv1 ] );
يعتمد عدد ونوع الوسائط بشكل كبير على كيفيّة تجميع العناصر ضمن الشّيفرة.
ملاحظات إضافيَّة
من تصميم jQuery أنّ الدوال البانية والتوابع الخاصَّة بها والتي تقبل سلاسل HTML نصيّة - مثل jQuery()، و append().، و .after() - تملك القدرة على تنفيذ أي شيفرة، قد يحدث هذا عن طريق حقن العنصر <script> أو استخدام خاصيّات HTML التي تُنفِّذ الشيفرة (مثل <img onload="">). لا تستخدم هذه التوابع لإدخال سلاسل نصيّة قادمة من مصادر غير موثوقة مثل مُعامِلات استعلام الرّوابط (URL query parameters)، أو الكعكات (cookies)، أو حقول الإدخال. يُؤدِّي فعل ذلك إلى ثغرات من نوع cross-site-scripting (اختصارًا XSS). قم بعمل إزالة أو تهريب للمحارف (escape) المُدخَلة بواسطة المستخدم قبل إضافة المحتوى للمستند.
لا تدعم jQuery بشكل رسمي مستندات SVG، وقد يُسبِّب استخدام توابع jQuery على مستندات SVG سلوكًا غير متوقع ما لم يكن ذلك مذكورًا في توثيق التّابع. من الأمثلة على توابع تدعم SVG بدءًا من إصدار jQuery 3.0 التّابع addClass و removeClass.
أمثلة
إضافة شيفرة HTML إلى جميع الفقرات:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>prepend مثالٌ عن استعمال التابع</title>
<style>
p {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>هذا هو صديقي</p>
<p>محمد</p>
<script>
$( "p" ).prepend( "<b>مرحبًا </b>" );
</script>
</body>
</html>
إضافة عنصر إلى جميع الفقرات:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>prepend مثالٌ عن استعمال التابع</title>
<style>
p {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>هو ما سأقوله</p>
<p>هو ما قلته</p>
<script>
$( "p" ).prepend( document.createTextNode( "مرحبًا " ) );
</script>
</body>
</html>
إضافة كائن jQuery (مماثل لإضافة مصفوفة من عناصر DOM) إلى جميع الفقرات:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>prepend مثالٌ عن استعمال التابع</title>
<style>
p {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p> هو ما قد قيل</p><b>مرحبًا</b>
<script>
$( "p" ).prepend( $( "b" ) );
</script>
</body>
</html>