`‎.parents([selector ])‎`

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

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

الوصف

يجلب هذا التابع جميع العناصر الآباء (العنصر الأب [parent] والأجداد [ancestors]) لكل عنصر في مجموعة العناصر المطابقة، ويمكن أن يرشِّح أيضًا تلك العناصر التي أعادها اختياريًا باستعمال محدِّد.

`‎.parents( [selector ] )‎`

أضيف مع الإصدار 1.0.

`selector`

سلسلة نصية تحتوي على تعبير محدِّد لمطابقة العناصر التي يجلبها التابع

عند إعطاء التابع ‎.parents()‎ كائن jQuery يمثل مجموعة من عناصر DOM، فسيبحث عن جميع العناصر الآباء لكل عنصر من هذه العناصر في شجرة DOM ثمَّ سينشئ كائنًا جديدًا من النوع jQuery ويضع فيه العناصر التي وجدها وطابقها، ويرتبها بدءًا من العنصر الأب الأقرب وحتى الأبعد. عندما يكون هنالك عناصر DOM متعدِّدة في المجموعة الأساسيَّة، فسيكون ترتيب المجموعة الناتجة عكس ترتيب تلك العناصر الأساسية مع حذف العناصر المتكررة.

يشبه هذا التابع التابع ‎.parent()‎ باستثناء أنَّ الأخير ينتقل مستوًى واحدًا إلى الأعلى فقط في شجرة DOM. يختلفان أيضًا بأنَّ التابع ‎$( "html" ).parent()‎ يعيد مجموعةً تحتوي على العنصر document بينما يعيد التابع ‎$( "html" ).parents()‎ مجموعةً فارغةً.

يقبل التابع أن يمرَّر إليه اختياريًّا تعبير محدِّد من النوع نفسه الذي يمكن تمريره إلى الدالة ‎$()‎‎. إن مُرِّر المحدد، فستُرشَّح العناصر بالتحقُّق من مطابقتها له أم لا.

بفرض أنَّه لدينا صفحة تحتوي على قائمة متشعبة بسيطة مثل:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">أ</li>
      <li class="item-b">ب
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">ج</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

إن بدأنا عند العنصر "أ"، فيمكننا إيجاد العناصر الآباء لهذا العنصر:

$( "li.item-a" ).parent().css( "background-color", "red" );

نتيجة هذا السطر هي تغيير لون خلفية القائمة "level-2"، والعنصر "II"، والقائمة "level-1" (ويستمر الصعود في شجرة DOM حتى الوصول إلى العنصر <html>) إلى اللون الأحمر. بما أنَّه لم نُمرِّر تعبير محدد، فسيضاف العنصر إلى الكائن المعاد. أمَّا إن مررنا تعبير محدِّد، فسيُتحقَق من مطابقة هذا العنصر أولًا ثمَّ سيُضاف إلى الكائن المعاد بناءً على ذلك.

أمثلة

إيجاد جميع العناصر الآباء لكل عنصر <b>:

<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>parents مثالٌ عن استعمال التابع</title>
  <style>
  b, span, p, html body {
    padding: .5em;
    border: 1px solid;
  }
  b {
    color: blue;
  }
  strong {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>
  <p>
    <span>
      <b>آبائي هم: </b>
    </span>
  </p>
</div>
 
<script>
var parentEls = $( "b" ).parents()
  .map(function() {
    return this.tagName;
  })
  .get()
  .join( ", " );
$( "b" ).append( "<strong>" + parentEls + "</strong>" );
</script>
 
</body>
</html>

الضغط على العنصر لإيجاد جميع العناصر <div> الآباء لكل عنصر <span>:

<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>parents مثالٌ عن استعمال التابع</title>
  <style>
  p, div, span {
    margin: 2px;
    padding: 1px;
  }
  div {
    border: 2px white solid;
  }
  span {
    cursor: pointer;
    font-size: 12px;
  }
  .selected {
    color: blue;
  }
  b {
    color: red;
    display: block;
    font-size: 14px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>
  <div>
    <div><span>السلام عليكم</span></div>
      <span>مرحبًا</span>
    </div>
    <div>
      <span>مرحبًا! هل يسمعني أحد؟</span>
    </div>
  </p>
  <b>اضغط على العنصر لمعرفة العناصر الآباء له</b>
 
<script>
function showParents() {
  $( "div" ).css( "border-color", "white" );
  var len = $( "span.selected" )
    .parents( "div" )
      .css( "border", "2px red solid" )
      .length;
  $( "b" ).text( "العناصر div الآباء هي: " + len );
}
$( "span" ).click(function() {
  $( this ).toggleClass( "selected" );
  showParents();
});
</script>
 
</body>
</html>

مصادر

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