التابع ‎.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( Integer index )‎ تُعيد سلسلة نصيّة من الكائن htmlString، أو عنصر أو عناصر DOM، أو عقدة أو عقد نصيّة، أو كائن jQuery المطلوب إدخالها قبل كل عنصر من مجموعة العناصر المُطابقة، يُمثِّل المعاملُ this العنصرَ الحالي. تستقبل فهرس موقع العنصر في المجموعة كوسيط لها.

‎.before( function-html )‎

أضيفت في الإصدار: 1.10.

function-html

دالة على الشكل Function( Integer index, String html )‎ تُعيد سلسلة نصيّة من الكائن htmlString، أو عنصر أو عناصر DOM، أو عقدة أو عقد نصيّة، أو كائن jQuery المطلوب إدخالها قبل كل عنصر من مجموعة العناصر المُطابقة. يُمثِّل المعاملُ this العنصرَ الحالي. تستقبل فهرس موقع العنصر في المجموعة وقيمة html القديمة للعنصر كوسائط لها.

يُنفِّذ التّابعان ‎.before()‎ و ‎.insertBefore()‎ نفس المهمّة. يكمن الفرق الأكبر بينهما في الصّياغة وتحديدًا في موضع المحتوى والهدف. حيث يأتي المحتوى المطلوب إدخاله في التّابع ‎.before()‎ من وسيط التّابع:

$(target).before(المحتوى المطلوب إدخاله)

بينما في التّابع ‎.insertBefore()‎ يسبق المحتوى التابع، ويضاف بعد ذلك الهدف، والذي يُمرَّر كوسيط للتابع:

$(المحتوى المطلوب إدخاله).insertBefore(target)

فلنأخذ مثال 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> على شكل ثلاثة وسائط مختلفة، كما يلي: