|
|
| سطر 1: |
سطر 1: |
| <noinclude>{{DISPLAYTITLE:التابع <code>jQuery.map()</code> في jQuery}}</noinclude> | | <noinclude>{{DISPLAYTITLE:التابع <code>jQuery.makeArray()</code> في jQuery}}</noinclude> |
| == <code>jQuery.map( array, callback )</code> == | | == <code>jQuery.makeArray( obj )</code> == |
|
| |
|
| === القيم المعادة === | | === القيم المعادة === |
| سطر 6: |
سطر 6: |
|
| |
|
| === الوصف === | | === الوصف === |
| يُمرِّر هذا التابع كلَّ عنصر من عناصر مصفوفة أو كائن إلى دالةٍ، ثمَّ ينشئ [[JavaScript/Array|مصفوفةً جديدةً]] تحتوي على القيم المعادة.
| | يحوِّل هذا التابع كائنًا شبيهًا بمصفوفة إلى [[JavaScript/Array|مصفوفة JavaScript حقيقية]]. |
|
| |
|
| === <code>jQuery.map( array, callback )</code> === | | === <code>jQuery.makeArray( obj )</code> === |
| أُضيف مع الإصدار: 1.0. | | أُضيف مع الإصدار: 1.4. |
|
| |
|
| ==== <code>array</code> ==== | | ==== <code>obj</code> ==== |
| [[JavaScript/Array|المصفوفة]] المراد تعديل جميع عناصرها.
| | الكائن المراد تحويله إلى مصفوفة فعليَّة. |
|
| |
|
| ==== <code>callback</code> ====
| | تعيد أغلب التوابع عمومًا، في [[jQuery]] و [[JavaScript]] كلاهما، كائنات شبيه بمصفوفة (array-like). فتعيد الدالة المنتجة <code>$()</code> مثلًا الكائن jQuery الذي يملك العديد من خاصِّيَّات المصفوفة (مثل الخاصِّيَّة <code>[[CSS/length|length]]</code>، والمعامل <code>[]</code> للوصول إلى المصفوفة ...إلخ.) إلا أنَّه ليس مصفوفة حقيقية تمامًا ويفتقد إلى بعض توابع المصفوفات المدمجة (مثل التابع <code>[[JavaScript/Array/pop|.pop()]]</code> والتابع <code>[[JavaScript/Array/reverse|.reverse()]]</code>). |
| دالةٌ من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Object|Object]] elementOfArray, [[JavaScript/Number|Number]] indexInArray )</code> ستعالج كل عنصر من عناصر المصفوفة على حدة. الوسيط الأول الممرَّر إلى هذه الدالة هو عنصر المصفوفة الحالي، والوسيط الثاني هو فهرس هذا العنصر في المصفوفة. يمكن أن تعيد هذه الدالة أي شيء، إذ ستوضع النتائج التي تعيدها الدالة في مصفوفة ثمَّ تعاد هذه المصفوفة. يشير <code>this</code> ضمن الدالة إلى الكائن window العام.
| |
|
| |
|
| === <code>jQuery.map( object, callback )</code> ===
| | انتبه إلى أنَّه لم تَعد أيَّة ميزات خاصَّة يملكها الكائن (مثل توابع jQuery في مثالنا السابق) موجودةً بعد تنفيذ عملية التحويل، إذ يصبح الكائن حينئذٍ مصفوفة صرفة. |
| أُضيفت مع الإصدار: 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">
| | تحويل مجموعة من عناصر [[HTML]] إلى مصفوفة تحتوي على هذه العناصر:<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.map demo</title> | | <title>jQuery.makeArray مثالٌ عن استعمال التابع</title> |
| <style> | | <style> |
| div { | | div { |
| color: blue;
| |
| }
| |
| p {
| |
| color: green;
| |
| margin: 0;
| |
| }
| |
| span {
| |
| color: red; | | color: red; |
| } | | } |
| سطر 73: |
سطر 34: |
| <body> | | <body> |
| | | |
| <div></div> | | <div>واحد</div> |
| <p></p> | | <div>اثنان</div> |
| <span></span> | | <div>ثلاثة</div> |
| | <div>أربعة</div> |
| | | |
| <script> | | <script> |
| var arr = [ "a", "b", "c", "d", "e" ]; | | // NodeList إعادة قائمة عقد |
| $( "div" ).text( arr.join( ", " ) );
| | var elems = document.getElementsByTagName( "div" ); |
|
| | // إلى مصفوفة NodeList تحويل قائمة العقد |
| arr = jQuery.map( arr, function( n, i ) { | | var arr = jQuery.makeArray( elems ); |
| return ( n.toUpperCase() + i );
| | // DOM استعمال أحد توابع المصفوفة مع قائمة عناصر |
| });
| | arr.reverse(); |
| $( "p" ).text( arr.join( ", " ) );
| | $( arr ).appendTo( document.body ); |
|
| |
| arr = jQuery.map( arr, function( a ) {
| |
| return a + a;
| |
| });
| |
| $( "span" ).text( arr.join( ", " ) );
| |
| </script> | | </script> |
| | | |
| سطر 95: |
سطر 52: |
| </html> | | </html> |
|
| |
|
| </syntaxhighlight>ستُظهر هذه الشيفرة النتيجة التالية:<syntaxhighlight lang="text"> | | </syntaxhighlight>تحويل الكائن jQuery إلى مصفوفة:<syntaxhighlight lang="javascript"> |
| a, b, c, d, e
| | var obj = $( "li" ); |
| A0, B1, C2, D3, E4
| | var arr = $.makeArray( obj ); |
| 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"> | | </syntaxhighlight>سنحصل عند تنفيذ هذه الشيفرة على النتيجة التالية:<syntaxhighlight lang="text"> |
| [ 0, 1, 4, 9 ]
| | ( typeof obj === "object" && obj.jquery ) === true; |
| </syntaxhighlight>إزالة الأعداد التي أقل من العدد 50 عبر إعادة [[JavaScript/null|القيمة العدميَّة]] (null) ثمَّ طرح القيمة 49 من القيم المتبقيَّة:<syntaxhighlight lang="javascript">
| | jQuery.isArray( arr ) === true; |
| $.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.map/ صفحة التابع ()jQuery.map في توثيق jQuery الرسمي.] | | * [http://api.jquery.com/jQuery.makeArray/ صفحة التابع ()jQuery.makeArray في توثيق jQuery الرسمي.] |
| [[تصنيف:jQuery]] | | [[تصنيف:jQuery]] |
| [[تصنيف:jQuery Method]] | | [[تصنيف:jQuery Method]] |
| [[تصنيف:jQuery Utilities]] | | [[تصنيف:jQuery Utilities]] |
jQuery.makeArray( obj )
القيم المعادة
يعيد مصفوفةً (Array).
الوصف
يحوِّل هذا التابع كائنًا شبيهًا بمصفوفة إلى مصفوفة JavaScript حقيقية.
jQuery.makeArray( obj )
أُضيف مع الإصدار: 1.4.
obj
الكائن المراد تحويله إلى مصفوفة فعليَّة.
تعيد أغلب التوابع عمومًا، في jQuery و JavaScript كلاهما، كائنات شبيه بمصفوفة (array-like). فتعيد الدالة المنتجة $() مثلًا الكائن jQuery الذي يملك العديد من خاصِّيَّات المصفوفة (مثل الخاصِّيَّة length، والمعامل [] للوصول إلى المصفوفة ...إلخ.) إلا أنَّه ليس مصفوفة حقيقية تمامًا ويفتقد إلى بعض توابع المصفوفات المدمجة (مثل التابع .pop() والتابع .reverse()).
انتبه إلى أنَّه لم تَعد أيَّة ميزات خاصَّة يملكها الكائن (مثل توابع jQuery في مثالنا السابق) موجودةً بعد تنفيذ عملية التحويل، إذ يصبح الكائن حينئذٍ مصفوفة صرفة.
أمثلة
تحويل مجموعة من عناصر HTML إلى مصفوفة تحتوي على هذه العناصر:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.makeArray مثالٌ عن استعمال التابع</title>
<style>
div {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div>واحد</div>
<div>اثنان</div>
<div>ثلاثة</div>
<div>أربعة</div>
<script>
// NodeList إعادة قائمة عقد
var elems = document.getElementsByTagName( "div" );
// إلى مصفوفة NodeList تحويل قائمة العقد
var arr = jQuery.makeArray( elems );
// DOM استعمال أحد توابع المصفوفة مع قائمة عناصر
arr.reverse();
$( arr ).appendTo( document.body );
</script>
</body>
</html>
تحويل الكائن jQuery إلى مصفوفة:
var obj = $( "li" );
var arr = $.makeArray( obj );
سنحصل عند تنفيذ هذه الشيفرة على النتيجة التالية:
( typeof obj === "object" && obj.jquery ) === true;
jQuery.isArray( arr ) === true;
مصادر