التابع `‎‎.replaceWith()‎`‎ في jQuery

`‎.replaceWith( newContent )‎`

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

يعيد كائنًا من النوع jQuery.

الوصف

يبدِّل هذا التابع المحتوى الجديد المعطى مكان كل عنصر في مجموعة العناصر المطابقة، ويعيد مجموعة العناصر التي استُبدلت.

`‎.replaceWith( newContent )‎`

أُضيف مع الإصدار: 1.2.

`newContent`

المحتوى الجديد الذي سيحل محل عناصر محدَّدة، وقد يكون سلسلة نصيَّة من الكائن htmlString أو عنصر DOM أو مصفوفة من عناصر DOM أو كائن jQuery.

`‎.replaceWith( function )‎`

أُضيف مع الإصدار: 1.4.

`function`

دالة من الشكل Function()‎، وتعيد المحتوى الذي سيُستبدل بمجموعة العناصر المطابقة.

يحذف التابع ‎.replaceWith()‎ المحتوى من عناصر DOM ويضع مكانه المحتوى الجديد المعطى عند استدعائه. بفرض أنَّ لدينا البنية DOM التالية:

<div class="container">
  <div class="inner first">مرحبًا</div>
  <div class="inner second">ثم</div>
  <div class="inner third">وداعًا</div>
</div>

يمكن تبديل محتوى HTML محدَّد مكان العنصر <div> الثاني الداخلي:

$( "div.second" ).replaceWith( "<h2>عنوان جديد</h2>" );

سيعطي هذا المثال الناتج التالي:

<div class="container">
  <div class="inner first">مرحبًا</div>
  <h2>عنوان جديد</h2>
  <div class="inner third">وداعًا</div>
</div>

أو يمكننا استبدال جميع العناصر <div> الداخلية في الوقت ذاته:

$( "div.inner" ).replaceWith( "<h2>عنوان جديد</h2>" );

سيؤدي ذلك إلى استبدال جميع العناصر:

<div class="container">
  <h2>عنوان جديد</h2>
  <h2>عنوان جديد</h2>
  <h2>عنوان جديد</h2>
</div>

أو يمكننا تحديد عنصر من المجموعة نفسها واستبدال عنصرٍ آخرٍ به:

$( "div.third" ).replaceWith( $( ".first" ) );

سنحصل على الناتج التالي:

<div class="container">
  <div class="inner second">ثم</div>
  <div class="inner first">مرحبًا</div>
</div>

نلاحظ من المثال السابق أنَّ عملية الاستبدال قد حصلت بانتقال العنصر من مكانه إلى مكان العنصر المحدَّد وليس بنسخه إلى المكان المستهدف وبقائه في مكانه أيضًا.

يعيد التابع ‎.replaceWith()‎ كائن jQuery، مثل أغلب توابع jQuery، لذا يمكن أن تعتمد توابع أخرى على هذا الناتج وتستخدمه. على أية حال، يجب الانتباه إلى أنَّه يعاد الكائن jQuery الأصلي الذي يشير إلى العناصر التي استُبدلت وحذفت من DOM وليس العناصر الجديدة التي استبدلتها.

ملاحظات إضافية

يحذف التابع ‎.replaceWith()‎ جميع البيانات ومعالجات الحدث المرتبطة بالعقد المحذوفة.

كان التابع ‎.replaceWith()‎ قبل الإصدار jQuery 1.9 يحاول أن يضيف أو يعدل العقد في مجموعة jQuery الحاليَّة إذا كانت العقدة الأولى في المجموعة غير مرتبطة بالمستند، وستُعاد في هذه الحالات مجموعة jQuery جديدة عوضًا عن المجموعة الأصلية. ربما يعيد التابع أو لا يعيد نتيجة جديدة اعتمادًا على عدد وسائطه أو ترابطها (connectedness). بدءًا من الإصدار jQuery 1.9، أصبح كلٌ من التوابع ‎.after()‎، و ‎.before()‎، و ‎.replaceWith()‎ يعيد دومًا المجموعة الأصليَّة غير المعدلة. ولم يعد هنالك أي تأثير لمحاولة استعمال هذه التوابع مع عقدة ليس لها عنصر أب، وبذلك لن تتغير المجموعة ولا حتى العقد الموجودة بداخلها.

أمثلة

تبديل العنصر <div> مكان العنصر <button> أينما وجد عند الضغط عليه مع الاحتفاظ بالنص الموجود داخله:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>replaceWith مثالٌ عن استعمال التابع</title>
  <style>
  button {
    display: block;
    margin: 3px;
    color: red;
    width: 200px;
  }
  div {
    color: red;
    border: 2px solid blue;
    width: 200px;
    margin: 3px;
    text-align: center;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>العنصر الأول</button>
<button>العنصر الثاني </button>
<button>العنصر الثالث</button>
 
<script>
$( "button" ).click(function() {
  $( this ).replaceWith( "<div>" + $( this ).text() + "</div>" );
});
</script>
 
</body>
</html>

استبدال كلمات معيَّنة بجميع الفقرات <p> الموجودة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>replaceWith مثالٌ عن استعمال التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا</p>
<p>يا</p>
<p>أحمد</p>
 
<script>
$( "p" ).replaceWith( "<b>فقرة </b>" );
</script>
 
</body>
</html>

تبديل العنصر <div> الموجود مسبقًا في DOM والمحدَّد باستعمال الدالة ‎$()‎ مكان كل فقرة <p> عند الضغط عليها. لاحظ أنه لا يُنسخ العنصر <div> وإنما ينقل ليحل مكان الفقرة <p>:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>replaceWith مثالٌ عن استعمال التابع</title>
  <style>
  div {
    border: 2px solid blue;
    color: red;
    margin: 3px;
  }
  p {
    border: 2px solid red;
    color: blue;
    margin: 3px;
    cursor: pointer;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
  <p>مرحبًا</p>
  <p>يا</p>
  <p>أحمد</p>
  <div>استُبدل!</div>
 
<script>
$( "p" ).click(function() {
  $( this ).replaceWith( $( "div" ) );
});
</script>
 
</body>
</html>

تبديل العناصر <div> الأبناء مكان العنصر <div> الأب الذي يحتويها عند الضغط على الزر، وإضافة اسم الصنف للعنصر المحدد إلى الفقرة <p>:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>replaceWith مثالٌ عن استعمال التابع</title>
  <style>
  .container {
    background-color: #991;
  }
  .inner {
    color: #911;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>
  <button>استبدل</button>
</p>
<div class="container">
  <div class="inner">محمد</div>
  <div class="inner">أمير</div>
  <div class="inner">السالم</div>
</div>
 
<script>
$( "button" ).on( "click", function() {
  var $container = $( "div.container" ).replaceWith(function() {
    return $( this ).contents();
  });
 
  $( "p" ).append( $container.attr( "class" ) );
});
</script>
 
</body>
</html>

مصادر

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