عرض مصدر jQuery/jQuery/map

<noinclude>{{DISPLAYTITLE:التابع <code>‎‎jQuery.map()‎</code>‎ في jQuery}}</noinclude>
== <code>jQuery.map( array, callback )‎</code> ==

=== القيم المعادة ===
يعيد [[JavaScript/Array|مصفوفةً]] (Array).

=== الوصف ===
يُمرِّر هذا التابع كلَّ عنصر من عناصر مصفوفة أو كائن إلى دالةٍ، ثمَّ ينشئ [[JavaScript/Array|مصفوفةً جديدةً]] تحتوي على القيم المعادة.

=== <code>jQuery.map( array, callback )‎</code> ===
أُضيف مع الإصدار: 1.0.

==== <code>array</code> ====
[[JavaScript/Array|المصفوفة]] المراد تعديل جميع عناصرها.

==== <code>callback</code> ====
دالةٌ من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Object|Object]] elementOfArray, [[JavaScript/Number|Number]] indexInArray )‎</code> ستعالج كل عنصر من عناصر المصفوفة على حدة. الوسيط الأول الممرَّر إلى هذه الدالة هو عنصر المصفوفة الحالي، والوسيط الثاني هو فهرس هذا العنصر في المصفوفة. يمكن أن تعيد هذه الدالة أي شيء، إذ ستوضع النتائج التي تعيدها الدالة في مصفوفة ثمَّ تعاد هذه المصفوفة. يشير <code>this</code> ضمن الدالة إلى الكائن window العام.

=== <code>jQuery.map( object, callback )‎</code> ===
أُضيفت مع الإصدار: 1.6.

==== <code>object</code> ====
الكائن المراد تبديل جميع عناصره.

==== <code>callback</code> ====
دالةٌ من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Object|Object]] propertyOfObject, [[JavaScript/String|String]] key )</code>‎ ستعالج كل خاصِّيَّة من خاصِّيَّات الكائن على حدة. الوسيط الأول الممرَّر إلى هذه الدالة هو قيمة خاصِّيَّة الكائن، والوسيط الثاني هو مفتاح هذه الخاصِّيَّة. يمكن أن تعيد هذه الدالة أي شيء، إذ ستوضع النتائج التي تعيدها الدالة في مصفوفة ثمَّ تعاد هذه المصفوفة. يشير <code>this</code> ضمن الدالة إلى الكائن window العام.

إن أردت معالجة الكائن [[jQuery/jQuery|jQuery]]، مثل ‎<code>$('div').map( callback )‎;</code>‎، فاستعمل التابع <code>[[jQuery/map|‎.map()‎]]</code> عوضًا عن هذا التابع.

يطبِّق التابع <code>‎$.map()‎</code> دالةً على كل عنصر من عناصر مصفوفة أو كائن، ثمَّ ينشئ مصفوفة جديدة ويضع فيها النتائج التي تعيدها الدالة.

بدءًا من الإصدار jQuery، أصبح التابع يدعم كائنات التنقُّل (traverses objects) أيضًا، إذ كان قبل هذا الإصدار يدعم مصفوفات التنقل (traversing arrays) فقط.

يجب تحويل الكائنات الشبيهة بالمصفوفات -تلك التي تملك الخاصِّيَّة <code>[[CSS/length|‎.length]]</code> وقيمةً عند الفهرس ‎<code>.length</code> - 1- إلى مصفوفات حقيقية قبل تمريها إلى التابع ‎<code>$.map()</code>‎. توفِّر مكتبة jQuery التابع ‎<code>[[jQuery/jQuery/makeArray|$.makeArray()]]</code>‎ الذي بإمكانه تنفيذ عملية التحويل هذه.<syntaxhighlight lang="javascript">
// الكائن التالي يتنكر في زِيِّ مصفوفة
var fakeArray = { "length": 2, 0: "Addy", 1: "Subtracty" };
 
// لذا، يجب تحويله إلى مصفوفة حقيقية
var realArray = $.makeArray( fakeArray )
 
// بثقة $.map() يمكن الآن استعمال التابع
$.map( realArray, function( val, i ) {
  // افعل شيئًا هنا
});
</syntaxhighlight>تُستدعَى الدالة المعطاة في التابع في هذا المثال لكلِّ عنصر ذي المستوى الأعلى (top-level)  في المصفوفة أو الكائن، ويمرَّر إليها وسيطين هما: قيمة العنصر، وفهرس موقعه في المصفوفة أو المفتاح المقابل له في الكائن.

يمكن للدالة أن تعيد:
* القيمة الممرَّرة إليها بعد معالجتها، إذ ستضاف هذه القيم حينئذٍ إلى المصفوفة المعادة؛
* أو القيمة [[JavaScript/null|العدميَّة]] (null) أو [[JavaScript/undefined|غير المعرَّفة]] (undefined)، ولن تضاف هذه القيمة حينها إلى المصفوفة المعادة؛
* أو مصفوفةً أو قيمًا والتي ستضاف إلى المصفوفة بأكملها.

=== أمثلة ===
استعمال التابع ‎<code>$.map()</code>‎ لتعديل قيم مصفوفة:<syntaxhighlight lang="html">
<!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>

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
a, b, c, d, e
A0, B1, C2, D3, E4
A0A0, B1B1, C2C2, D3D3, E4E4

</syntaxhighlight>إضافة العدد 4 إلى كل عنصر من عناصر مصفوفة ثمَّ وضع القيم في مصفوفة جديدة:<syntaxhighlight lang="javascript">
$.map( [ 0, 1, 2 ], function( n ) {
 return n + 4;
});

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[4, 5, 6]
</syntaxhighlight>إضافة العدد 1 إلى كل عنصر من عناصر مصفوفة شرط أن يكون أكبر من الصفر تمامًا، أو إزالته إن لم يكن ثمَّ إعادة القيم في مصفوفة جديدة:<syntaxhighlight lang="javascript">
$.map( [ 0, 1, 2 ], function( n ) {
 return n > 0 ? n + 1 : null;
});

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ 2, 3 ]
</syntaxhighlight>إعادة كل عنصر من عناصر مصفوفة مرةً نفسه وأخرى مضافًا إليه القيمة 1 ثمَّ وضع العناصر المعادة في مصفوفة جديدة:<syntaxhighlight lang="javascript">
$.map( [ 0, 1, 2 ], function( n ) {
   return [ n, n + 1 ];
});

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ 0, 1, 1, 2, 2, 3 ]
</syntaxhighlight>مضاعفة كل قيمة من قيم الكائن وإعادتها في مصفوفة:<syntaxhighlight lang="javascript">
var dimensions = { العرض : 10, الارتفاع: 15, الطول: 20 };
dimensions = $.map( dimensions, function( value, index ) {
 return value * 2;
});
</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ 20, 30, 40 ]
</syntaxhighlight>وضع جميع مفاتيح كائنٍ ضمن مصفوفة:<syntaxhighlight lang="javascript">
var dimensions = { العرض: 10, الارتفاع: 15, الطول: 20 };
var keys = $.map( dimensions, function( value, key ) {
 return key;
});

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ "العرض", "الارتفاع", "الطول" ]
</syntaxhighlight>تربيع كل قيمة متواجدة في المصفوفة وإعادتها في مصفوفة جديدة:<syntaxhighlight lang="javascript">
$.map( [ 0, 1, 2, 3 ], function( a ) {
 return a * a;
});


</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ 0, 1, 4, 9 ]
</syntaxhighlight>إزالة الأعداد التي أقل من العدد 50 عبر إعادة [[JavaScript/null|القيمة العدميَّة]] (null) ثمَّ طرح القيمة 49 من القيم المتبقيَّة:<syntaxhighlight lang="javascript">
$.map( [ 0, 1, 52, 97 ], function( a ) {
 return (a > 50 ? a - 45 : null);
});

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ 7, 52 ]
</syntaxhighlight>زيادة عناصر المصفوفة الناتجة عن المصفوفة المُمرَّرة عبر إعادة مصفوفة داخل الدالة:<syntaxhighlight lang="javascript">
var array = [ 0, 1, 52, 97 ];
array = $.map( array, function( a, index ) {
 return [ a - 45, index ];
});

</syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text">
[ -45, 0, -44, 1, 7, 2, 52, 3]
</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/jQuery.map/ صفحة التابع ()jQuery.map في توثيق jQuery الرسمي.]
[[تصنيف:jQuery]]
[[تصنيف:jQuery Method]]
[[تصنيف:jQuery Utilities]]