التابع jQuery.grep() في jQuery
jQuery.grep( array, function [, invert ] )
القيم المعادة
يعيد مصفوفةً من النوع Array.
الوصف
يبحث هذا التابع عن عناصر مصفوفة تتطابق مع الدالة المرشِّحة المعطاة ثمَّ يعيد هذه العناصر بطريقة لا تتأثر فيها المصفوفة الأصليَّة.
jQuery.grep( array, function [, invert ] )
أُضيفت مع الإصدار: 1.0.
array
كائنٌ شبيهٌ بمصفوفة (array-like object) يراد البحث ضمنه.
function
دالةٌ من الشكل Function( Object elementOfArray, Number indexInArray ) تعالج كل عنصر من عناصر الوسيط array المعطى. الوسيط الأول الممرَّر إلى هذه الدالة هو العنصر المراد معالجته، والوسيط الثاني هو فهرس هذا العنصر، ويجب أن تعيد قيمة منطقيَّة. يشير this ضمن الدالة إلى الكائن window العام.
invert
قيمة منطقيَّة (Boolean). إن كانت false أو لم تعطَ مطلقًا، فستعاد مصفوفةً تحتوي على جميع العناصر التي أعادت الدالة function القيمة true لها. أمَّا إن كانت قيمة هذا الوسيط true، فستعاد مصفوفةً تحتوي على جميع العناصر التي أعادت الدالة function القيمة false لها.
تنتقي الدالة $.grep() جميع العناصر التي تجتاز اختبارًا محدَّدًا من المصفوفة المعطاة. هذا الاختبار هو دالةٌ يمرَّر إليها العنصر الحالي من عناصر المصفوفة وفهرس موقعه ضمن تلك المصفوفة؛ وإن كانت نتيجة الاختبار الذي يخضع له العنصر آنذاك true، فسيدرج هذا العنصر ضمن المصفوفة الناتجة (يمكن انتقاء العناصر التي تحصل على النتيجة false عند خضوعها للاختبار مع تمرير القيمة false للوسيط invert).
أمثلة
ترشيح عناصر مصفوفة تحتوي على أعدادٍ بإبقاء الأعداد التي لا تساوي 5 وقيمة فهرسها أكبر من 4 ثمَّ إزالة العناصر التي قيمتها 9:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.grep مثالٌ عن استعمال التابع</title>
<style>
div {
color: blue;
}
p {
color: green;
margin: 0;
}
span {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div></div>
<p></p>
<span></span>
<script>
var arr = [ 1, 9, 3, 8, 6, 1, 5, 9, 4, 7, 3, 8, 6, 9, 1 ];
$( "div" ).text( arr.join( ", " ) );
arr = jQuery.grep(arr, function( n, i ) {
return ( n !== 5 && i > 4 );
});
$( "p" ).text( arr.join( ", " ) );
arr = jQuery.grep(arr, function( a ) {
return a !== 9;
});
$( "span" ).text( arr.join( ", " ) );
</script>
</body>
</html>
نتيجة تنفيذ المثال السابق هي:
1, 9, 3, 8, 6, 1, 5, 9, 4, 7, 3, 8, 6, 9, 1
1, 9, 4, 7, 3, 8, 6, 9, 1
1, 4, 7, 3, 8, 6, 1
ترشيح عناصر مصفوفة تحتوي على أعدادٍ عبر ترك العناصر التي قيمتها أكبر تمامًا من الصفر:
$.grep( [ 0, 1, 2 ], function( n, i ) {
return n > 0;
});
سنحصل عند تنفيذ هذه الشيفرة على النتيجة التالية:
[ 1, 2 ]
ترشيح عناصر مصفوفة تحتوي على أعدادٍ عبر ترك العناصر التي قيمتها أصغر أو تساوي الصفر:
$.grep( [ 0, 1, 2 ], function( n, i ) {
return n < 0;
}, true );
سنحصل عند تنفيذ هذه الشيفرة على النتيجة التالية:
[ 0 ]