التابع jQuery.map() في jQuery
jQuery.map( array, callback )
القيم المعادة
يعيد مصفوفةً (Array).
الوصف
يُمرِّر هذا التابع كلَّ عنصر من عناصر مصفوفة أو كائن إلى دالةٍ، ثمَّ ينشئ مصفوفةً جديدةً تحتوي على القيم المعادة.
jQuery.map( array, callback )
أُضيف مع الإصدار: 1.0.
array
المصفوفة المراد تعديل جميع عناصرها.
callback
دالةٌ من الشكل Function( Object elementOfArray, Number indexInArray ) ستعالج كل عنصر من عناصر المصفوفة على حدة. الوسيط الأول الممرَّر إلى هذه الدالة هو عنصر المصفوفة الحالي، والوسيط الثاني هو فهرس هذا العنصر في المصفوفة. يمكن أن تعيد هذه الدالة أي شيء، إذ ستوضع النتائج التي تعيدها الدالة في مصفوفة ثمَّ تعاد هذه المصفوفة. يشير this ضمن الدالة إلى الكائن window العام.
jQuery.map( object, callback )
أُضيفت مع الإصدار: 1.6.
object
الكائن المراد تبديل جميع عناصره.
callback
دالةٌ من الشكل Function( Object propertyOfObject, String key ) ستعالج كل خاصِّيَّة من خاصِّيَّات الكائن على حدة. الوسيط الأول الممرَّر إلى هذه الدالة هو قيمة خاصِّيَّة الكائن، والوسيط الثاني هو مفتاح هذه الخاصِّيَّة. يمكن أن تعيد هذه الدالة أي شيء، إذ ستوضع النتائج التي تعيدها الدالة في مصفوفة ثمَّ تعاد هذه المصفوفة. يشير this ضمن الدالة إلى الكائن window العام.
إن أردت معالجة الكائن jQuery، مثل $('div').map( callback );، فاستعمل التابع .map() عوضًا عن هذا التابع.
يطبِّق التابع $.map() دالةً على كل عنصر من عناصر مصفوفة أو كائن، ثمَّ ينشئ مصفوفة جديدة ويضع فيها النتائج التي تعيدها الدالة.
بدءًا من الإصدار jQuery، أصبح التابع يدعم كائنات التنقُّل (traverses objects) أيضًا، إذ كان قبل هذا الإصدار يدعم مصفوفات التنقل (traversing arrays) فقط.
يجب تحويل الكائنات الشبيهة بالمصفوفات -تلك التي تملك الخاصِّيَّة .length وقيمةً عند الفهرس .length - 1- إلى مصفوفات حقيقية قبل تمريها إلى التابع $.map(). توفِّر مكتبة jQuery التابع $.makeArray() الذي بإمكانه تنفيذ عملية التحويل هذه.
// الكائن التالي يتنكر في زِيِّ مصفوفة
var fakeArray = { "length": 2, 0: "Addy", 1: "Subtracty" };
// لذا، يجب تحويله إلى مصفوفة حقيقية
var realArray = $.makeArray( fakeArray )
// بثقة $.map() يمكن الآن استعمال التابع
$.map( realArray, function( val, i ) {
// افعل شيئًا هنا
});
تُستدعَى الدالة المعطاة في التابع في هذا المثال لكلِّ عنصر ذي المستوى الأعلى (top-level) في المصفوفة أو الكائن، ويمرَّر إليها وسيطين هما: قيمة العنصر، وفهرس موقعه في المصفوفة أو المفتاح المقابل له في الكائن.
يمكن للدالة أن تعيد:
- القيمة الممرَّرة إليها بعد معالجتها، إذ ستضاف هذه القيم حينئذٍ إلى المصفوفة المعادة؛
- أو القيمة العدميَّة (null) أو غير المعرَّفة (undefined)، ولن تضاف هذه القيمة حينها إلى المصفوفة المعادة؛
- أو مصفوفةً أو قيمًا والتي ستضاف إلى المصفوفة بأكملها.
أمثلة
استعمال التابع $.map() لتعديل قيم مصفوفة:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.map demo</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 = [ "a", "b", "c", "d", "e" ];
$( "div" ).text( arr.join( ", " ) );
arr = jQuery.map( arr, function( n, i ) {
return ( n.toUpperCase() + i );
});
$( "p" ).text( arr.join( ", " ) );
arr = jQuery.map( arr, function( a ) {
return a + a;
});
$( "span" ).text( arr.join( ", " ) );
</script>
</body>
</html>
ستُظهر هذه الشيفرة النتيجة التالية:
a, b, c, d, e
A0, B1, C2, D3, E4
A0A0, B1B1, C2C2, D3D3, E4E4
إضافة العدد 4 إلى كل عنصر من عناصر مصفوفة ثمَّ وضع القيم في مصفوفة جديدة:
$.map( [ 0, 1, 2 ], function( n ) {
return n + 4;
});
ستُظهر هذه الشيفرة النتيجة التالية:
[4, 5, 6]
إضافة العدد 1 إلى كل عنصر من عناصر مصفوفة شرط أن يكون أكبر من الصفر تمامًا، أو إزالته إن لم يكن ثمَّ إعادة القيم في مصفوفة جديدة:
$.map( [ 0, 1, 2 ], function( n ) {
return n > 0 ? n + 1 : null;
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ 2, 3 ]
إعادة كل عنصر من عناصر مصفوفة مرةً نفسه وأخرى مضافًا إليه القيمة 1 ثمَّ وضع العناصر المعادة في مصفوفة جديدة:
$.map( [ 0, 1, 2 ], function( n ) {
return [ n, n + 1 ];
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ 0, 1, 1, 2, 2, 3 ]
مضاعفة كل قيمة من قيم الكائن وإعادتها في مصفوفة:
var dimensions = { العرض : 10, الارتفاع: 15, الطول: 20 };
dimensions = $.map( dimensions, function( value, index ) {
return value * 2;
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ 20, 30, 40 ]
وضع جميع مفاتيح كائنٍ ضمن مصفوفة:
var dimensions = { العرض: 10, الارتفاع: 15, الطول: 20 };
var keys = $.map( dimensions, function( value, key ) {
return key;
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ "العرض", "الارتفاع", "الطول" ]
تربيع كل قيمة متواجدة في المصفوفة وإعادتها في مصفوفة جديدة:
$.map( [ 0, 1, 2, 3 ], function( a ) {
return a * a;
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ 0, 1, 4, 9 ]
إزالة الأعداد التي أقل من العدد 50 عبر إعادة القيمة العدميَّة (null) ثمَّ طرح القيمة 49 من القيم المتبقيَّة:
$.map( [ 0, 1, 52, 97 ], function( a ) {
return (a > 50 ? a - 45 : null);
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ 7, 52 ]
زيادة عناصر المصفوفة الناتجة عن المصفوفة المُمرَّرة عبر إعادة مصفوفة داخل الدالة:
var array = [ 0, 1, 52, 97 ];
array = $.map( array, function( a, index ) {
return [ a - 45, index ];
});
ستُظهر هذه الشيفرة النتيجة التالية:
[ -45, 0, -44, 1, 7, 2, 52, 3]