التابع .prependTo() في jQuery
.prependTo( target )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يُستخدَم هذا التابع في إدخال كل عنصر من مجموعة العناصر المُطابِقة إلى بداية العنصر الهدف.
.prependTo( target )
أضيف مع الإصدار 1.0.
target
مُحدِّد (Selector) أو سلسلة نصيّة من الكائن htmlString أو عنصر أو مصفوفة أو كائن jQuery، وتُمثِّل مجموعة العناصر المُطابِقة التي ستُدخَل إلى بداية العنصر أو العناصر المُحدَّدة عن طريق هذا المُعامِل.
ينجز التابعان .prepend() و .prependTo() نفس المهمة ويكمن الفرق الأساسي بينهما في الصياغة، أي في مكان تحديد المحتوى والعناصر الهدف، فبالنسبة للتابع ،.prepend() يُشير تعبير المُحدِّد (selector) الذي يسبق التابع إلى الحاوية التي سيُدخَل إليها المحتوى، أما في التابع .prependTo()، المحتوى الذي يسبق التابع هو إمّا كتعبير مُحدِّد أو كعناصر HTML مُنشأة بشكل مباشر، ويُدخَل إلى الحاوية الهدف.
فلنأخذ مثلًا شيفرة HTML التالية:
<h2>السلام عليكم</h2>
<div class="container">
<div class="inner">مرحبًا</div>
<div class="inner">وداعًا</div>
</div>
بإمكاننا إنشاء المحتوى وإدخاله إلى عناصر متعدِّدة بنفس الوقت:
$( "<p>تجربة</p>" ).prependTo( ".inner" );
سيحصل كل عنصر <div> على المحتوى الجديد:
<h2>السلام عليكم</h2>
<div class="container">
<div class="inner">
<p>تجربة</p>
مرحبًا
</div>
<div class="inner">
<p>تجربة</p>
وداعًا
</div>
</div>
بإمكاننا أيضًا تحديد عنصر من الصفحة وإدخاله إلى عنصر آخر:
$( "h2" ).prependTo( $( ".container" ) );
إن أدخلنا عنصرًا مختارًا بهذه الطريقة إلى موقع واحد في أي مكان من DOM، فسينتقل إلى العنصر الهدف (ولن يُنسَخ):
<div class="container">
<h2>السلام عليكم</h2>
<div class="inner">مرحبًا</div>
<div class="inner">وداعًا</div>
</div>
إن كان هنالك أكثر من عنصر هدف، فستُنشَأ نسخة من العنصر المُدخَل لكل عنصر هدف ما عدا العنصر الأخير.
ملاحظات إضافيّة
من تصميم 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.
أمثلة
إضافة كافّة عناصر <span> إلى العنصر الذي يمتلك المُعرِّف "foo" (انظر إلى توثيق .prepend() للمزيد من الأمثلة):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>prependTo مثالٌ عن استعمال التابع</title>
<style>
div {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="foo">ماذا تقول؟ </div>
<span>ليس لدي شيئًا لأقوله</span>
<script>
$( "span" ).prependTo( "#foo" );
</script>
</body>
</html>