التابع .parentsUntil() في jQuery
.parentsUntil( [selector ] [, filter ] )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يجلب هذا التابع العناصر الآباء (العنصر الأب [parent] والأجداد [ancestors]) الواقعة بين العنصر الأب الأقرب وحتى العنصر المتطابق باستعمال محدِّد، أو عقدة DOM، أو كائن jQuery (لا يدخل هذا العنصر ضمن المجال) وذلك لكل عنصر في مجموعة العناصر المطابقة، مع إمكانية ترشيحها بشكل اختياري عن طريق محدِّد.
.parentsUntil( [selector ] [, filter ] )
أضيف مع الإصدار 1.4.
selector
سلسلة نصية تحتوي على تعبير محدِّد يشير إلى العنصر الذي سيتوقف عنده جلب ومطابقة العناصر الآباء.
filter
سلسلة نصية تحتوي على تعبير محدِّد يطابق العناصر الآباء التي يُعثر عليها.
.parentsUntil( [element ] [, filter ] )
أضيف مع الإصدار 1.6.
element
عقدة DOM أو كائن jQuery يشير إلى العنصر الذي سيتوقف عنده جلب ومطابقة العناصر الآباء.
filter
سلسلة نصية تحتوي على تعبير محدِّد يطابق العناصر الآباء التي يُعثر عليها.
عند إعطاء التابع .parentsUntil() تعبير محدِّد يمثِّل مجموعة من عناصر DOM، فسيبحث عن العناصر الآباء لكل عنصر من هذه العناصر في شجرة DOM صعودًا حتى يصل إلى العنصر المتطابق باستعمال الوسيط selector المعطى؛ ينشئ بعدئذٍ كائنًا جديدًا من النوع jQuery ويضع فيه تلك العناصر التي وجدها بعد أن يطابقها باستعمال المرشح filter (إن مُرِّر إلى التابع)، ولا يدخل العنصر المتطابق باستعمال الوسيط selector المعطى ضمن مجال العناصر المعادة.
إن لم يُعطَ الوسيط selector أو أعطي ولكن لم يتطابق أي عنصر، فستُعاد حينذاك جميع العناصر الآباء أي سيعيد في هذه الحالة نفس العناصر التي يعيدها التابع .parents() عندما لا يُمرَّر إليه أي وسيط.
بدءًا من الإصدار jQuery 1.6، أصبح بالإمكان استعمال عنصر DOM أو كائن jQuery عوضًا عن المحدِّد المعطى في الوسيط selector الأول.
يقبل التابع أن يمرَّر إليه اختياريًّا تعبير محدِّد كوسيطٍ ثانٍ. إن أعطي هذا الوسيط، فستُرشَّح العناصر التي يعثر عليها التابع عبر التحقُّق من مطابقتها له أم لا.
أمثلة
إيجاد العناصر الآباء للعنصر <li class="item-a"> وحتى العنصر <ul class="level-1"> وتغيير لون خلفيتهم إلى اللون الأحمر. وإيجاد العناصر الآباء للعنصر <li class="item-2"> وحتى العنصر <ul class="level-1"> أيضًا شرط أن تكون من الصنف "yes" وتغيير لون إطارهم إلى الأخضر:
<!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>