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