الفرق بين المراجعتين لصفحة: «jQuery/append»

المراجعة الحالية بتاريخ 09:21، 24 يونيو 2018

`‎.append( content [, content ] )‎`

القيمة المعادة

كائن jQuery.

الوصف

يُستخدَم التّابع ‎.append()‎ في إدخال المحتوى المُحدَّد عن طريق المُعامِل إلى آخر كل عنصر من مجموعة العناصر المُطابِقة.

`‎.append( content [, content ] )‎`

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

content

سلسلة نصيّة من الكائن htmlString، أو عنصر، أو نص، أو مصفوفة، أو jQuery، وتُمثِّل سلسلة HTML، أو عنصر DOM، أو عقدة نصيّة (text node)، أو مصفوفة من العناصر والعقد النصيّة، أو كائن jQuery المطلوب إدخالها بعد كل عنصر من مجموعة العناصر المُطابقة.

`content`

سلسلة نصيّة من الكائن htmlString، أو عنصر، أو نص، أو مصفوفة، أو jQuery، وتُمثِّل عنصرًا إضافيًا واحدًا أو أكثر من عناصر DOM، أو العقد النصيّة (text node)، أو مصفوفات من العناصر والعقد النصية، أو سلسلة HTML، أو كائنات jQuery المطلوب إدخالها بعد كل عنصر من مجموعة العناصر المُطابقة.

`‎.append( function )‎`

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

`function`

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

يُدخِل التّابع ‎.append()‎ المحتوى المُحدَّد كآخر ابن (last child) لكل عنصر من مجموعة jQuery (لإدخاله كأول ابن استخدم التّابع ‎.prepend()‎).

ينجز التّابعان ‎.append()‎ و ‎.appendTo()‎ نفس المهمة ويكمن الفرق الأساسي بينهما في الصّياغة، أي في مكان تحديد المحتوى والعناصر الهدف، فبالنسبة للتابع ‎.append()‎ يُشير تعبير المُحدِّد (selector) الذي يسبق التّابع إلى الحاوية التي سيُدخَل إليها المحتوى، أما في التّابع ‎‎.appendTo()‎ يسبق المحتوى التّابع إمّا كتعبير مُحدِّد أو كعناصر HTML مُنشأة بشكل مباشر، ويُدخَل إلى الحاوية الهدف.

فلنأخذ مثال HTML التالي:

<h2>تحيّات</h2>
<div class="container">
  <div class="inner">مرحبًا</div>
  <div class="inner">وداعًا</div>
</div>

بإمكاننا إنشاء المحتوى وإدخاله إلى عناصر متعدّدة بنفس الوقت:

$( ".inner" ).append( "<p>تجربة</p>" );

سيحصل كل عنصر <div> على المحتوى الجديد:

<h2>تحيّات</h2>
<div class="container">
  <div class="inner">
    مرحبًا
    <p>تجربة</p>
  </div>
  <div class="inner">
    وداعًا
    <p>تجربة</p>
  </div>
</div>

بإمكاننا أيضًا تحديد عنصر من الصفحة وإدخاله إلى عنصر آخر:

$( ".container" ).append( $( "h2" ) );

إن أدخلنا عنصرًا مختارًا بهذه الطريقة إلى موقع واحد في أي مكان من DOM، فسينتقل إلى العنصر الهدف (ولن يُنسَخ):

<div class="container">
  <div class="inner">مرحبًا</div>
  <div class="inner">وداعًا</div>
  <h2>تحيّات</h2>
</div>

ملاحظة مهمة: إن كان هنالك أكثر من عنصر هدف، فستُنشَأ نسخة من العنصر المُدخَل لكل عنصر هدف ما عدا العنصر الأخير.

وسائط إضافيّة

كما هو الحال مع توابع إضافة المحتوى الأخرى مثل ‎.prepend()‎ و ‎.before()‎، يدعم التّابع ‎.append()‎ تمرير وسائط متعدّة كمُدخلات. من المُدخلات المدعومة عناصر DOM، وكائنات jQuery، وسلاسل HTML النصيّة، ومصفوفات من عناصر DOM.

على سبيل المثال سيُدخِل المثال التالي عنصري <div> جديدين وعنصر <div> موجود كآخر ثلاثة أبناء للعنصر <body>:

var $newdiv1 = $( "<div id='object1'></div>" ),
  newdiv2 = document.createElement( "div" ),
  existingdiv1 = document.getElementById( "foo" );
 
$( "body" ).append( $newdiv1, [ newdiv2, existingdiv1 ] );

لمّا كان التّابع ‎.append()‎ يقبل أي عدد من الوسائط الإضافيّة، فيُمكِن تحقيق نفس النتيجة عن طريق تمرير عناصر <div> الثلاث كوسائط منفصلة كما يلي:

$('body').append( $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="en">
<head>
  <meta charset="utf-8">
  <title>مثال عن الإضافة</title>
  <style>
  p {
    background: yellow;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>أرغب في أن أقول: </p>
 
<script>
$( "p" ).append( "<strong>مرحبًا</strong>" );
</script>
 
</body>
</html>

إضافة عنصر إلى جميع الفقرات:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>مثال عن الإضافة</title>
  <style>
  p {
    background: yellow;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>أرغب في أن أقول: </p>
 
<script>
$( "p" ).append( document.createTextNode( "مرحبًا" ) );
</script>
 
</body>
</html>

إضافة كائن jQuery (مماثل لإضافة مصفوفة من عناصر DOM) إلى جميع الفقرات:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>مثال عن الإضافة</title>
  <style>
  p {
    background: yellow;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<strong>مرحبًا!!!</strong>
<p>أرغب في أن أقول: </p>
 
<script>
$( "p" ).append( $( "strong" ) );
</script>
 
</body>
</html>

مصادر

صفحة التابع ‎.append()‎ في توثيق jQuery الرسمي.