jQuery/closest

‎.closest( selector )‎

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

كائن jQuery.

الوصف

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

‎.closest( selector )‎

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

selector

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

‎.closest( selector [, context ] )‎

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

selector

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

context

عنصر، ويُمثِّل عنصر DOM الذي قد يُوجَد ضمنه عنصر مُطابِق.

‎.closest( selection )‎

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

selection

كائن jQuery، ويُمثِّل كائن jQuery المطلوب مُطابقة العناصر معه.

‎.closest( element )‎

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

element

عنصر، ويُمثِّل العنصر المطلوب مُطابقة العناصر معه.

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

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

<ul id="one" class="level-1">
  <li class="item-i">I</li>
  <li id="ii" class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">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">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

فلنفترض أنّنا بحثنا عن عناصر <ul‎> بدءًا من العنصر A:

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

سيُغيّر هذا لون القائمة <ul‎> ذات الصنف level-2 ، بما أنّه أول عنصر <ul‎> نُصادفه عند الانتقال للأعلى في شجرة DOM. فلنفترض أنّنا نريد البحث عن العنصر <li‎> بدلًا من ذلك:

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

سُغيِّر هذا من لون العنصر A من القائمة، حيث يبدأ التّابع ‎.closest()‎ بحثه ضمن العنصر نفسه قبل الانتقال إلى الأعلى في شجرة DOM، ويتوقّف عندما يجد أنّ العنصر A مُطابِق للمُحدِّد المطلوب. بإمكاننا تمرير عنصر DOM إلى الوسيط context والذي يجب البحث ضمنه عن أقرب عنصر:

var listItemII = document.getElementById( "ii" );
$( "li.item-a" )
  .closest( "ul", listItemII )
  .css( "background-color", "red" );
$( "li.item-a" )
  .closest( "#one", listItemII )
  .css( "background-color", "green" );

سيُغيِّر هذا لون عنصر <ul‎> ذي الصّنف level-2، لأنّه في نفس الوقت أول عنصر سليف للعنصر A، وهو عنصر مُنحدِر عن القائمة التي تملك المُعرِّف ii ، لن يتغيّر لون عنصر <ul‎> ذي الصّنف level-1 لأنّه ليس عنصرًا مُنحدِرًا عن القائمة التي تملك المُعرِّف ii.