التابع .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) وذلك عند الضغط على العنصر المنحدر عنه:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>closest مثال عن التابع</title>
<style>
li {
margin: 3px;
padding: 3px;
background: #EEEEEE;
}
li.highlight {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<ul>
<li><b>انقر هنا!</b></li>
<li>بإمكانك أيضًا <b>النقر هنا!</b></li>
</ul>
<script>
$( document ).on( "click", function( event ) {
$( event.target ).closest( "li" ).toggleClass( "highlight" );
});
</script>
</body>
</html>
تمرير كائن jQuery إلى التّابع .closest()، سيُبدِّل عنصر القائمة الأقرب بين وضعيتين للخلفيّة (صفراء وغير صفراء عن طريق تطبيق الصّنف highlight) وذلك عند الضغط على العنصر المنحدر عنه:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>closest مثال عن التابع</title>
<style>
li {
margin: 3px;
padding: 3px;
background: #EEEEEE;
}
li.highlight {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<ul>
<li><b>انقر هنا!</b></li>
<li>بإمكانك أيضًا <b>النقر هنا!</b></li>
</ul>
<script>
var listElements = $( "li" ).css( "color", "blue" );
$( document ).on( "click", function( event ) {
$( event.target ).closest( listElements ).toggleClass( "highlight" );
});
</script>
</body>
</html>
.closest( selectors [, context ] )
القيمة المعادة
أُهمل هذا الشكل من التابع بدءًا من الإصدار 1.7، وأزيل في الإصدار 1.8.
الوصف
يُستخدَم هذا الشكل من التابع .closest() للحصول على مصفوفة تتألف من جميع العناصر والمُحدِّدات المُطابِقة ابتداءً من العنصر الحالي وانتقالًا للأعلى عبر شجرة DOM.
.closest( selectors [, context ] )
أضيفت في الإصدار: 1.4.
selectors
مصفوفة Array، وتُمثِّل مصفوفة أو سلسلة نصيّة تحتوي على تعبير المُحدِّد المطلوب مُطابقة العناصر معه (يُمكِن أن يكون كائن jQuery أيضًا).
context
عنصر، ويُمثِّل عنصر DOM الذي قد يُوجَد ضمنه عنصر مُطابِق.
ملاحظة: أُهمل هذا الشكل من التابع بدءًا من الإصدار 1.7 فقط، وأزيل في الإصدار 1.8. وكان يهدف أن يُستخدَم بشكل رئيسي داخليًّا أو عن طريق مبرمجي الإضافات.