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

`‎.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.

أمثلة

إظهار كيفيّة عمل تفويض الأحداث (event delegation) عن طريق التّابع ‎.closest()‎، سيُبدِّل عنصر القائمة الأقرب بين وضعيتين للخلفيّة (صفراء وغير صفراء عن طريق تطبيق الصّنف highlight) وذلك عند الضغط على العنصر المنحدر عنه: