الفرق بين المراجعتين لصفحة: «jQuery/jQuery/map»
جميل-بيلوني (نقاش | مساهمات) إضافة محتويات الصفحة. |
جميل-بيلوني (نقاش | مساهمات) تصحيح الصفحة. |
||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:التابع <code>jQuery. | <noinclude>{{DISPLAYTITLE:التابع <code>jQuery.map()</code> في jQuery}}</noinclude> | ||
== <code>jQuery. | |||
== <code>jQuery.map( array, callback )</code> == | |||
=== القيم المعادة === | === القيم المعادة === | ||
| سطر 6: | سطر 7: | ||
=== الوصف === | === الوصف === | ||
يُمرِّر هذا التابع كلَّ عنصر من عناصر مصفوفة أو كائن إلى دالةٍ، ثمَّ ينشئ مصفوفةً جديدةً تحتوي على القيم المعادة. | |||
=== <code>jQuery.map( array, callback )</code> === | |||
أُضيف مع الإصدار: 1.0. | |||
==== <code>array</code> ==== | |||
المصفوفة المراد تعديل جميع عناصرها. | |||
==== <code>callback</code> ==== | |||
دالةٌ من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Object|Object]] elementOfArray, [[JavaScript/Number|Number]] indexInArray )</code> ستعالج كل عنصر من عناصر المصفوفة على حدة. الوسيط الأول الممرَّر إلى هذه الدالة هو عنصر المصفوفة الحالي، والوسيط الثاني هو فهرس هذا العنصر في المصفوفة. يمكن أن تعيد هذه الدالة أي شيء، إذ ستوضع النتائج التي تعيدها الدالة في مصفوفة ثمَّ تعاد هذه المصفوفة. يشير <code>this</code> ضمن الدالة إلى الكائن <code>window</code> العام. | |||
=== <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> ضمن الدالة إلى الكائن <code>window</code> العام. | |||
إن أردت معالجة الكائن [[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)، ولن تضاف هذه القيمة حينها إلى المصفوفة المعادة؛ | |||
* أو [[JavaScript/Array|مصفوفةً]] أو قيمًا والتي ستضاف إلى المصفوفة بأكملها. | |||
=== أمثلة === | === أمثلة === | ||
استعمال التابع <code>$.map()</code> لتعديل قيم مصفوفة:<syntaxhighlight lang="html"> | |||
<!doctype html> | <!doctype html> | ||
<html lang="en"> | <html lang="en"> | ||
<head> | <head> | ||
<meta charset="utf-8"> | <meta charset="utf-8"> | ||
<title>jQuery. | <title>jQuery.map demo</title> | ||
<style> | <style> | ||
div { | div { | ||
color: blue; | |||
} | |||
p { | |||
color: green; | |||
margin: 0; | |||
} | |||
span { | |||
color: red; | color: red; | ||
} | } | ||
| سطر 34: | سطر 74: | ||
<body> | <body> | ||
<div> | <div></div> | ||
< | <p></p> | ||
<span></span> | |||
< | |||
<script> | <script> | ||
var arr = [ "a", "b", "c", "d", "e" ]; | |||
var | $( "div" ).text( arr.join( ", " ) ); | ||
arr = jQuery.map( arr, function( n, i ) { | |||
return ( n.toUpperCase() + i ); | |||
arr. | }); | ||
$( | $( "p" ).text( arr.join( ", " ) ); | ||
arr = jQuery.map( arr, function( a ) { | |||
return a + a; | |||
}); | |||
$( "span" ).text( arr.join( ", " ) ); | |||
</script> | </script> | ||
| سطر 52: | سطر 96: | ||
</html> | </html> | ||
</syntaxhighlight> | </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>ستُظهر هذه الشيفرة النتيجة التالية:<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> | </syntaxhighlight> | ||
== مصادر == | == مصادر == | ||
* [http://api.jquery.com/jQuery. | * [http://api.jquery.com/jQuery.map/ صفحة التابع ()jQuery.map في توثيق jQuery الرسمي.] | ||
[[تصنيف:jQuery]] | [[تصنيف:jQuery]] | ||
[[تصنيف:jQuery Method]] | [[تصنيف:jQuery Method]] | ||
[[تصنيف:jQuery Utilities]] | [[تصنيف:jQuery Utilities]] | ||
المراجعة الحالية بتاريخ 16:17، 1 يوليو 2018
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]