عرض مصدر jQuery/parentsUntil

<noinclude>{{DISPLAYTITLE:التابع <code>‎‎.parentsUntil()‎</code>‎ في jQuery}}</noinclude>
= <code>‎.parentsUntil( [selector ] [, filter ] )‎</code> =

=== القيم المعادة ===
يعيد كائنًا من النوع [[jQuery/jQuery|jQuery]].

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

=== <code>‎.parentsUntil( [selector ] [, filter ] )‎</code> ===
أضيف مع الإصدار 1.4.

==== <code>selector</code> ====
سلسلة نصية تحتوي على تعبير محدِّد يشير إلى العنصر الذي سيتوقف عنده جلب ومطابقة العناصر الآباء.

==== <code>filter</code> ====
سلسلة نصية تحتوي على تعبير محدِّد يطابق العناصر الآباء التي يُعثر عليها.

=== <code>‎.parentsUntil( [element ] [, filter ] )‎</code> ===
أضيف مع الإصدار 1.6.

==== <code>element</code> ====
عقدة DOM أو كائن [[jQuery/jQuery|jQuery]] يشير إلى العنصر الذي سيتوقف عنده جلب ومطابقة العناصر الآباء.

==== <code>filter</code> ====
سلسلة نصية تحتوي على تعبير محدِّد يطابق العناصر الآباء التي يُعثر عليها.

عند إعطاء التابع <code>‎.parentsUntil()‎</code> تعبير محدِّد يمثِّل مجموعة من عناصر DOM، فسيبحث عن العناصر الآباء لكل عنصر من هذه العناصر في شجرة DOM صعودًا حتى يصل إلى العنصر المتطابق باستعمال الوسيط <code>selector</code> المعطى؛ ينشئ بعدئذٍ كائنًا جديدًا من النوع [[jQuery/jQuery|jQuery]] ويضع فيه تلك العناصر التي وجدها بعد أن يطابقها باستعمال المرشح <code>filter</code> (إن مُرِّر إلى التابع)، ولا يدخل العنصر المتطابق باستعمال الوسيط <code>selector</code> المعطى ضمن مجال العناصر المعادة.

إن لم يُعطَ الوسيط <code>selector</code> أو أعطي ولكن لم يتطابق أي عنصر، فستُعاد حينذاك جميع العناصر الآباء أي سيعيد في هذه الحالة نفس العناصر التي يعيدها التابع <code>[[jQuery/parents|‎.parents()]]</code>‎ عندما لا يُمرَّر إليه أي وسيط.

بدءًا من الإصدار jQuery 1.6، أصبح بالإمكان استعمال عنصر DOM أو كائن [[jQuery/jQuery|jQuery]] عوضًا عن المحدِّد المعطى في الوسيط <code>selector</code> الأول.

يقبل التابع أن يمرَّر إليه اختياريًّا تعبير محدِّد كوسيطٍ ثانٍ. إن أعطي هذا الوسيط، فستُرشَّح العناصر التي يعثر عليها التابع عبر التحقُّق من مطابقتها له أم لا.

== أمثلة ==
إيجاد العناصر الآباء للعنصر <code>[[HTML/li|<nowiki><li class="item-a"‎></nowiki>]]</code> وحتى العنصر <code>[[HTML/ul|<nowiki><ul class="level-1"‎></nowiki>]]</code> وتغيير لون خلفيتهم إلى اللون الأحمر. وإيجاد العناصر الآباء للعنصر <code>[[HTML/li|<nowiki><li class="item-2"‎> و</nowiki>]]</code>حتى العنصر <code>[[HTML/ul|<nowiki><ul class="level-1"‎></nowiki>]]</code> أيضًا شرط أن تكون من الصنف "yes" وتغيير لون إطارهم إلى الأخضر:<syntaxhighlight lang="html">
<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>parentsUntil مثالٌ عن استعمال التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<ul class="level-1 yes">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2 yes">
      <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>
 
<script>
$( "li.item-a" )
  .parentsUntil( ".level-1" )
    .css( "background-color", "red" );
 
$( "li.item-2" )
  .parentsUntil( $( "ul.level-1" ), ".yes" )
    .css( "border", "3px solid green" );
</script>
 
</body>
</html>

</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/parentsUntil/ صفحة التابع ‎‎.parentsUntil()‎‎ في توثيق jQuery الرسمي.]
[[تصنيف:jQuery]]
[[تصنيف:jQuery Traversing]]