التابع .filter() في jQuery
.filter( selector )
القيمة المعادة
يُعيد كائنًا من النوع jQuery.
الوصف
يقلص هذا التابع مجموعة العناصر المُطابقة إلى تلك التي تطابق المُحدد أو اجتازت اختبار الدالة.
.filter( selector )
أُضيف مع الإصدار: 1.0.
selector
سلسلة نصية من النوع Selector تحتوي على تعبير مُحدد لمطابقة المجموعة الحالية من العناصر.
.filter( function )
أُضيف مع الإصدار: 1.0.
function
دالة على الشكل Function( Integer index, Element element ) => Boolean
تُستخدم كاختبار لكل عنصر في المجموعة. ويُعد المعامل this هو عنصر DOM الحالي.
.filter( elements )
أُضيف مع الإصدار: 1.4.
elements
عنصر واحد أو أكثر من عناصر DOM لمطابقة المجموعة الحالية من العناصر، وهو من النوع Element.
.filter( selection )
أُضيف مع الإصدار: 1.4.
selection
كائن من النوع jQuery موجود لمطابقة المجموعة الحالية من العناصر.
بافتراض كائن jQuery يمثل مجموعة من عناصر DOM، يُنشِئ التابع .filter() كائن jQuery جديد من مجموعة فرعية من العناصر المطابقة. باختبار المحدد المُعطى مع كل عنصر، تُدرج جميع العناصر التي تطابق المحدد في النتيجة.
إليك صفحة بها قائمة بسيطة:
<ul>
<li>list item 1</li>
<li>list item 2</li>
<li>list item 3</li>
<li>list item 4</li>
<li>list item 5</li>
<li>list item 6</li>
</ul>
يمكننا تطبيق هذا التابع على مجموعة عناصر القائمة:
$( "li" ).filter( ":even" ).css( "background-color", "red" );
نتيجة هذا الاستدعاء تكون خلفية حمراء للعناصر 1 و 3 و 5، لأنها تتطابق مع المحدد (تذكر أن المحددان :even و :odd يستخدمان فهرسة صفرية).
استخدام دالة ترشيح
يسمح الشكل الثاني من هذا التابع لنا بترشيح العناصر باستخدام دالة بدلاً من محدد. لكل عنصر، إذا أعادت الدالة true (أو قيمة يمكن تفسيرها على أنها true)، فسيندرج العنصر في المجموعة المُرَشَجة. خلاف ذلك، سيستبعد. لنفترض أن لدينا مقتطف HTML التالي:
<ul>
<li><strong>list</strong> item 1 - one strong tag</li>
<li><strong>list</strong> item <strong>2</strong> -
two <span>strong tags</span></li>
<li>list item 3</li>
<li>list item 4</li>
<li>list item 5</li>
<li>list item 6</li>
</ul>
يمكننا تحديد عناصر القائمة، ثم ترشيحها تبعًا لمحتوياتها:
$( "li" )
.filter(function( index ) {
return $( "strong", this ).length === 1;
})
.css( "background-color", "red" );
ستغير هذه الشيفرة عنصر القائمة الأول فقط، لأنه يحتوي على عنصر <strong> واحد بالضبط. ضمن دالة الترشيح، يشير this إلى كل عنصر DOM بدوره. يخبرنا المعامل المُمرر إلى الدالة عن مؤشر عنصر DOM هذا داخل المجموعة المُطابقة بواسطة كائن jQuery.
يمكننا أيضًا الاستفادة من index المُمرر من خلال الدالة، والذي يشير إلى الموضع الصفري للعنصر داخل مجموعة العناصر التي لم تُرشَّح:
$( "li" )
.filter(function( index ) {
return index % 3 === 2;
})
.css( "background-color", "red" );
سيؤدي هذا التعديل في الشيفرة البرمجية إلى تمييز عناصر القائمة الثالث والسادس، نظرًا لأنها تستخدم عامل المعيار ( % ) لتحديد كل عنصر ذي قيمة index، عند القسمة على 3، ويكون الباقي 2.
ملاحظة: عند تمرير سلسلة محدد CSS إلى .filter()، يزال دائمًا النص وعُقَد التعليقات من كائن jQuery الناتج أثناء عملية الترشيح. عند إدخال عقدة معينة أو مصفوفة عُقَد، سيندرج النص أو عقدة التعليق في كائن jQuery الناتج فقط إذا كان يطابق أحد العقد في مصفوفة الترشيح.
أمثلة
تغيير لون جميع عناصر <div>؛ ثم إضافة إطار إلى العناصر التي تملك الصنف "middle":
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>filter demo</title>
<style>
div {
width: 60px;
height: 60px;
margin: 5px;
float: left;
border: 2px white solid;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div></div>
<div class="middle"></div>
<div class="middle"></div>
<div class="middle"></div>
<div class="middle"></div>
<div></div>
<script>
$( "div" )
.css( "background", "#c8ebcc" )
.filter( ".middle" )
.css( "border-color", "red" );
</script>
</body>
</html>
تغيير لون جميع عناصر <div>؛ ثم إضافة إطار إلى الثاني (فهرسه يساوي 1) وإلى عنصر <div> ذي المعرّف "fourth":
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>filter demo</title>
<style>
div {
width: 60px;
height: 60px;
margin: 5px;
float: left;
border: 3px white solid;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="first"></div>
<div id="second"></div>
<div id="third"></div>
<div id="fourth"></div>
<div id="fifth"></div>
<div id="sixth"></div>
<script>
$( "div" )
.css( "background", "#b4b0da" )
.filter(function( index ) {
return index === 1 || $( this ).attr( "id" ) === "fourth";
})
.css( "border", "3px double red" );
</script>
</body>
</html>
تحديد جميع عناصر <div> وترشيح التحديد باستخدام عنصر DOM، مع الاحتفاظ بالعنصر الذي له المُعرِّف "unique" فقط:
$( "div" ).filter( document.getElementById( "unique" ) );
تحديد جميع عناصر <div> وترشيح التحديد باستخدام كائن jQuery، مع الاحتفاظ بالعنصر الذي له المُعرِّف "unique" فقط:
$( "div" ).filter( $( "#unique" ) );