التابع .siblings() في jQuery
.siblings( [selector ] )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يجلب هذا التابع جميع العناصر الأخوة لكل عنصر في مجموعة العناصر المطابقة مع إمكانية ترشيحها باستعمال محدِّد معطى.
.siblings( [selector ] )
أُضيف مع الإصدار: 1.0.
selector
سلسلة نصية تحتوي على تعبير محدِّد لمطابقة العناصر.
عند إعطاء التابع .siblings() كائن jQuery يمثِّل مجموعة عناصر DOM، فسيبحث عن العناصر الأخوة لهذه العناصر في شجرة DOM ثمَّ ينشئ كائن jQuery جديد يضع فيه العناصر التي وجدها.
يقبل التابع اختياريًّا تعبير محدِّد لنفس النوع الذي يمكن تمريره إلى الدالة $(). إن طابقت تلك العناصر الأخوة هذا المحدِّد، فستبقى في كائن jQuery المُنشأ حديثًا آنذاك وإلا فستُستبعَد منه.
بفرض أنَّه لدينا صفحة تحتوي على قائمة بسيطة مثل:
<ul>
<li>العنصر الأول</li>
<li>العنصر الثاني</li>
<li class="third-item">العنصر الثالث</li>
<li>العنصر الرابع</li>
<li>العنصر الخامس</li>
</ul>
إن بدأنا عند العنصر الثالث، فسنعثر على العناصر الأخوة لهذا العنصر:
$( "li.third-item" ).siblings().css( "background-color", "red" );
سيكون نتيجة تنفيذ هذه الشيفرة هو تغيير لون خلفية العنصر الأول والثاني والرابع والخامس إلى اللون الأحمر. بما أنَّه لم نمرِّر تعبير محدِّد إلى التابع، فلا شك أنَّ هذا العنصر سيضاف إلى الكائن. إن زودنا التابع بتعبير محدِّد معين، فسيتحقَّق من تطابق العنصر قبل إضافته إلى الكائن.
لا يدخل العنصر الذي اخترناه لإيجاد العناصر الأخوة له ضمن الناتج المُعاد كما أوضح المثال ذلك، وهذا الأمر مهم عندما نريد تحديد جميع العناصر الواقعة في مستوى محدَّد من شجرة DOM. على أية حال، إن كان هذا العنصر هو مجموعة تحتوي على عنصر واحد أو أكثر، فقد يكون من بينها عناصر أخوة للعنصر المحدد وستُعاد حينئذٍ. إن أردت أن تستثني قائمة محدَّدة من العناصر الأخوة، فاستعمل $collection.siblings().not($collection).
أمثلة
إيجاد العناصر الأخوة لجميع العناصر <li> المميزة باللون الأصفر في القوائم الثلاث (يُسمح بأن تكون تلك العناصر عناصر أخوة أيضًا):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>siblings مثالٌ عن استعمال التابع</title>
<style>
ul {
float: left;
margin: 5px;
font-size: 16px;
font-weight: bold;
}
p {
color: blue;
margin: 10px 20px;
font-size: 16px;
padding: 5px;
font-weight: bolder;
}
.hilite {
background: yellow;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<ul>
<li>واحد</li>
<li>اثنان</li>
<li class="hilite">ثلاثة</li>
<li>أربعة</li>
</ul>
<ul>
<li>خمسة</li>
<li>ستة</li>
<li>سبعة</li>
</ul>
<ul>
<li>ثمانية</li>
<li class="hilite">تسعة</li>
<li>عشرة</li>
<li class="hilite">أحد عشر</li>
</ul>
<p>عدد العناصر الأخوة: <b></b></p>
<script>
var len = $( ".hilite" ).siblings()
.css( "color", "red" )
.length;
$( "b" ).text( len );
</script>
</body>
</html>
إيجاد جميع العناصر الأخوة لكل عنصر <div> شرط أن تكون من الصنف "selected":
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>siblings مثالٌ عن استعمال التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div><span>السلام عليكم</span></div>
<p class="selected">مرحبًا</p>
<p>كيف الحال؟</p>
<script>
$( "p" ).siblings( ".selected" ).css( "background", "yellow" );
</script>
</body>
</html>