الدالة jQuery.each() في jQuery
jQuery.each( array, callback )
القيم المعادة
تعيد كائنًا من النوع Object.
الوصف
هذه الدالة هي دالة تكرار عامة تستعمل لتكرار تنفيذ دالة بسلاسة تامة عبر الكائنات والمصفوفات. عدد مرات تكرار تنفيذ الدالة على المصفوفات والكائنات الشبيهة بالمصفوفات التي لها الخاصِّيَّة length (مثل الكائن الذي يحوي وسائط دالةٍ) تنحصر بالمجال من 0 إلى length-1، إذ length هو عدد العناصر. أمَّا عدد مرات تكرار الكائنات الأخرى تتعلق بالخصائص المسماة للكائن.
jQuery.each( array, callback )
أُضيف مع الإصدار: 1.0.
array
مصفوفةٌ أو كائنٌ شبيهٌ بمصفوفة يراد تكرار تنفيذ الدالة callback عليه.
callback
دالةٌ من الشكل Function( Number indexInArray, Object value ) يراد تكرار تنفيذها على جميع عناصر أو قيم المصفوفة array.
jQuery.each( object, callback )
أُضيف مع الإصدار: 1.0.
object
كائنٌ يراد تكرار تنفيذ الدالة callback عليه.
callback
دالةٌ من الشكل Function( String propertyName, Object valueOfProperty ) يراد تكرار تنفيذها على جميع قيم الكائن object.
لا تشبه الدالة $.each() التابع $(selector).each() الذي يستعمل لتكرار تنفيذ دالةٍ عبر كائن jQuery تحديدًا بينما يمكن استعمال الدالة لتكرار تنفيذ دالةٍ عبر أي مجموعة سواءً كانت هذه المجموعة مصفوفةً أو كائنًا. في حال كانت تلك المجموعة مصفوفةً، فيُمرَّر إلى الدالة callback المعطاة فهرس عناصر المصفوفة والقيمة المقابلة للعنصر الذي يشير إليه هذا الفهرس في كلِّ مرة. (يمكن الوصول إلى هذه القيمة أيضًا عبر الكلمة المحجوزة this إلا أنَّ JavaScript ستشير إلى قيمة this ككائن حتى لو كانت تلك القيمة سلسلة نصية أو قيمة رقمية.) سيعيد التابع وسيطه الأول أي الكائن الذي كُرِّر تنفيذ الدالة عليه.
$.each([ 52, 97 ], function( index, value ) {
alert( index + ": " + value );
});
سنحصل بعد تنفيذ هذه الشيفرة على الرسالتين التاليتين:
0: 52
1: 97
أمَّا إن كانت المجموعة كائنًا، فيمرَّر إلى الدالة callback الزوج مفتاح/قيمة في كلِّ مرة:
var obj = {
"flammable": "inflammable",
"duh": "no duh"
};
$.each( obj, function( key, value ) {
alert( key + ": " + value );
});
سنحصل أيضًا بعد تنفيذ الشيفرة على الرسالتين التاليتين:
flammable: inflammable
duh: no duh
يمكن كسر حلقة تكرار الدالة $.each() عند تكرار محدَّد بجعل الدالة callback تعيد القيمة false عند الوصول إلى هذا التكرار. إعادة قيمة مغايرة للقيمة false تشير إلى الاستمرار والانتقال إلى عمليَّة التكرار التالية، وكأنَّها تمثِّل العبارة continue.
أمثلة
إظهار كل رقم كقيمة نصية ورقمية عبر تطبيق هذه العمليَّة وتكرارها على جميع عناصر مصفوفة:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.each مثالٌ عن استعمال الدالة</title>
<style>
div {
color: blue;
}
div#five {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
<div id="four"></div>
<div id="five"></div>
<script>
var arr = [ "واحد", "اثنان", "ثلاثة", "أربعة", "خمسة" ];
var obj = { واحد: 1, اثنان: 2, ثلاثة: 3, أربعة: 4, خمسة: 5 };
jQuery.each( arr, function( i, val ) {
$( "#" + val ).text( "رقمي " + val + "." );
// "التوقف عند القيمة "ثلاثة
return ( val !== "three" );
});
jQuery.each( obj, function( i, val ) {
$( "#" + i ).append( document.createTextNode( " - " + val ) );
});
</script>
</body>
</html>
إظهار فهرس ومحتوى كل عنصر من عناصر المصفوفة:
$.each( [ "a", "b", "c" ], function( i, l ){
alert( "الفهرس #" + i + ": " + l );
});
إظهار مفتاح وقيمة كل عنصر من عناصر الكائن:
$.each({ name: "John", lang: "JS" }, function( k, v ) {
alert( "Key: " + k + ", Value: " + v );
});