Array.prototype.map()‎

الدالة Array.prototype.map()‎ تُنشِئ مصفوفةً جديدةً باستخدام القيم المُعادة من استدعاء دالة مُحدَّدة على جميع عناصر المصفوفة الأصلية.

var array1 = [1, 4, 9, 16];

// دالة سهمية
const map1 = array1.map(x => x * 2);

console.log(map1); // [2, 8, 18, 32]

البنية العامة

var new_array = arr.map(callback[, thisArg])

callback

الدالة التي ستختبر كل عنصر من عناصر المصفوفة، وتقبل ثلاثة وسائط.

currentValue

العنصر الحالي الذي يُعالِج في المصفوفة، وهذه القيمة مطلوبة.

index

فهرس العنصر الحالي في المصفوفة، وهذه القيمة اختيارية.

array

المصفوفة التي استدعيت الدالة map عليها، وهذه القيمة اختيارية.

thisArg

القيمة التي ستُستخدَم في this عند استدعاء الدالة callback، وهي قيمة اختيارية.

القيمة المعادة

مصفوفة جديدة فيها القيم المُعادة من الدالة المُحدَّدة التي تعالج قيم المصفوفة الأصلية.

الوصف

الدالة map تُنفِّذ الدالة callback على كل عنصر موجود في المصفوفة بالترتيب، وتُنشِئ دالةً جديدةً بناءً على القيم المُعادة من تلك الدالة. لاحظ أنَّ الدالة callback ستُستدعى على الفهارس التي لها قيمٌ مسندةٌ إليها، فهي لن تستدعى للفهارس التي حُذِفَت أو التي لم تُسنَد إليها قيم.

ستستدعى الدالة callback مع تمرير ثلاثة وسائط إليها: قيمة العنصر، وفهرسه، وكائن المصفوفة التي ستُختَبر عناصرها.

إذا وفّرنا المعامل thisArg إلى الدالة map، فسيستخدم كقيمة this داخل الدالة callback، وإن لم نُحدِّد له قيمةً فستستعمل القيمة undefined.

لاحظ أنَّ الدالة map لا تغيّر المصفوفة التي تستدعى عليها بأيّ شكلٍ من الأشكال.

أمثلة

إنشاء مصفوفة بالجذور التربيعية الأعداد في المصفوفة الأصلية

الشيفرة الآتية تأخذ مصفوفةً من الأرقام وتُنشِئ مصفوفةً جديدةً تحتوي على الجذور التربيعية للأعداد في أوّل مصفوفة:

var numbers = [1, 4, 9];
var roots = numbers.map(Math.sqrt);
// roots: [1, 2, 3]
// numbers: [1, 4, 9]

استخدام الدالة map لإعادة تنسيق الكائنات الموجودة في مصفوفة

المثال الآتي فيه مصفوفةٌ من الكائنات ونريد إعادة هيكلة تلك الكائنات، وسنستعين بالدالة map لفعل ذلك:

var kvArray = [{key: 1, value: 10}, 
               {key: 2, value: 20}, 
               {key: 3, value: 30}];

var reformattedArray = kvArray.map(function(obj) { 
   var rObj = {};
   rObj[obj.key] = obj.value;
   return rObj;
});

// reformattedArray: [{1: 10}, {2: 20}, {3: 30}], 

// kvArray: 
// [{key: 1, value: 10}, 
//  {key: 2, value: 20}, 
//  {key: 3, value: 30}]

استخدام الدالة map لقلب سلسلة نصية

var str = '12345';
Array.prototype.map.call(str, function(x) {
  return x;
}).reverse().join(''); 

// '54321'

تعويض نقص دعم المتصفحات

أضيفت هذه الدالة في الإصدار الخامس من معيار ECMAScript، لذا يمكنك استخدام الشيفرة الآتية لإضافتها للمتصفحات التي لا تدعمها:

// Production steps of ECMA-262, Edition 5, 15.4.4.19
// Reference: http://es5.github.io/#x15.4.4.19
if (!Array.prototype.map) {

  Array.prototype.map = function(callback/*, thisArg*/) {

    var T, A, k;

    if (this == null) {
      throw new TypeError('this is null or not defined');
    }

    // 1. Let O be the result of calling ToObject passing the |this| 
    //    value as the argument.
    var O = Object(this);

    // 2. Let lenValue be the result of calling the Get internal 
    //    method of O with the argument "length".
    // 3. Let len be ToUint32(lenValue).
    var len = O.length >>> 0;

    // 4. If IsCallable(callback) is false, throw a TypeError exception.
    // See: http://es5.github.com/#x9.11
    if (typeof callback !== 'function') {
      throw new TypeError(callback + ' is not a function');
    }

    // 5. If thisArg was supplied, let T be thisArg; else let T be undefined.
    if (arguments.length > 1) {
      T = arguments[1];
    }

    // 6. Let A be a new array created as if by the expression new Array(len) 
    //    where Array is the standard built-in constructor with that name and 
    //    len is the value of len.
    A = new Array(len);

    // 7. Let k be 0
    k = 0;

    // 8. Repeat, while k < len
    while (k < len) {

      var kValue, mappedValue;

      // a. Let Pk be ToString(k).
      //   This is implicit for LHS operands of the in operator
      // b. Let kPresent be the result of calling the HasProperty internal 
      //    method of O with argument Pk.
      //   This step can be combined with c
      // c. If kPresent is true, then
      if (k in O) {

        // i. Let kValue be the result of calling the Get internal 
        //    method of O with argument Pk.
        kValue = O[k];

        // ii. Let mappedValue be the result of calling the Call internal 
        //     method of callback with T as the this value and argument 
        //     list containing kValue, k, and O.
        mappedValue = callback.call(T, kValue, k, O);

        // iii. Call the DefineOwnProperty internal method of A with arguments
        // Pk, Property Descriptor
        // { Value: mappedValue,
        //   Writable: true,
        //   Enumerable: true,
        //   Configurable: true },
        // and false.

        // In browsers that support Object.defineProperty, use the following:
        // Object.defineProperty(A, k, {
        //   value: mappedValue,
        //   writable: true,
        //   enumerable: true,
        //   configurable: true
        // });

        // For best browser support, use the following:
        A[k] = mappedValue;
      }
      // d. Increase k by 1.
      k++;
    }

    // 9. return A
    return A;
  };
}

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	9	نعم	نعم

مصادر ومواصفات

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.
• معيار ECMAScript 5.1.