JavaScript/Array/from

الدالة Array.from()‎ تُنشِئ مصفوفة جديدة من كائن شبيه بالمصفوفات.

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

Array.from(arrayLike[, mapFn[, thisArg]])

arrayLike

الكائن الشبيه بالمصفوفات الذي نريد تحويله إلى مصفوفة.

mapFn

دالة الربط (map function) التي ستستدعى على كل عنصر من عناصر المصفوفة.

thisArg

القيمة التي ستستخدم في this عند استدعاء mapFn.

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

مصفوفة جديدة.

الوصف

الدالة Array.from()‎ تسمح بإنشاء مصفوفات من كائنات شبيهة بالمصفوفات (array-like objects)، أي الكائنات التي لها الخاصية length وفيها عناصر مُفهرَسة.

تملك الدالة Array.from()‎ وسيطًا اختياريًا باسم mapFn، الذي يسمح بتنفيذ دالة map على كل عنصر من عناصر المصفوفة التي ستُنشَأ.

لاحظ أنَّ قيمة length للدالة from()‎ هي 1.

أمثلة

مصفوفة من String

Array.from('foo'); 
// ["f", "o", "o"]

مصفوفة من Set

var s = new Set(['foo', window]); 
Array.from(s); 
// ["foo", window]

مصفوفة من Map

var m = new Map([[1, 2], [2, 4], [4, 8]]);
Array.from(m); 
// [[1, 2], [2, 4], [4, 8]]

مصفوفة من كائن شبيه بالمصفوفات (arguments)

function f() {
  return Array.from(arguments);
}

f(1, 2, 3);

// [1, 2, 3]

استخدام الدوال السهمية مع Array.from()‎

استخدام دالة سهمية في المعامل mapFn لتعديل القيم المُضافة إلى المصفوفة:

Array.from([1, 2, 3], x => x + x);      
// [2, 4, 6]

توليد سلسلة من الأرقام، ولمّا كانت المصفوفة مُهيّئة مع القيم undefined في كل موضع، فستكون قيمة v في المثال الآتي هي undefined:

Array.from({length: 5}, (v, i) => i);
// [0, 1, 2, 3, 4]

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

أُضيفَت الدالة Array.from أوّل مرة في معيار ECMAScript 2015 (أي ES6)، وهذا يعني أنَّ هنالك بعض المتصفحات التي لم تدعم هذه الدالة بعد، لكن يمكن الالتفاف على هذه المشكلة باستخدام الشيفرة الآتية:

// Production steps of ECMA-262, Edition 6, 22.1.2.1
if (!Array.from) {
  Array.from = (function () {
    var toStr = Object.prototype.toString;
    var isCallable = function (fn) {
      return typeof fn === 'function' || toStr.call(fn) === '[object Function]';
    };
    var toInteger = function (value) {
      var number = Number(value);
      if (isNaN(number)) { return 0; }
      if (number === 0 || !isFinite(number)) { return number; }
      return (number > 0 ? 1 : -1) * Math.floor(Math.abs(number));
    };
    var maxSafeInteger = Math.pow(2, 53) - 1;
    var toLength = function (value) {
      var len = toInteger(value);
      return Math.min(Math.max(len, 0), maxSafeInteger);
    };

    // The length property of the from method is 1.
    return function from(arrayLike/*, mapFn, thisArg */) {
      // 1. Let C be the this value.
      var C = this;

      // 2. Let items be ToObject(arrayLike).
      var items = Object(arrayLike);

      // 3. ReturnIfAbrupt(items).
      if (arrayLike == null) {
        throw new TypeError('Array.from requires an array-like object - not null or undefined');
      }

      // 4. If mapfn is undefined, then let mapping be false.
      var mapFn = arguments.length > 1 ? arguments[1] : void undefined;
      var T;
      if (typeof mapFn !== 'undefined') {
        // 5. else
        // 5. a If IsCallable(mapfn) is false, throw a TypeError exception.
        if (!isCallable(mapFn)) {
          throw new TypeError('Array.from: when provided, the second argument must be a function');
        }

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

      // 10. Let lenValue be Get(items, "length").
      // 11. Let len be ToLength(lenValue).
      var len = toLength(items.length);

      // 13. If IsConstructor(C) is true, then
      // 13. a. Let A be the result of calling the [[Construct]] internal method 
      // of C with an argument list containing the single item len.
      // 14. a. Else, Let A be ArrayCreate(len).
      var A = isCallable(C) ? Object(new C(len)) : new Array(len);

      // 16. Let k be 0.
      var k = 0;
      // 17. Repeat, while k < len… (also steps a - h)
      var kValue;
      while (k < len) {
        kValue = items[k];
        if (mapFn) {
          A[k] = typeof T === 'undefined' ? mapFn(kValue, k) : mapFn.call(T, kValue, k);
        } else {
          A[k] = kValue;
        }
        k += 1;
      }
      // 18. Let putStatus be Put(A, "length", len, true).
      A.length = len;
      // 20. Return A.
      return A;
    };
  }());
}

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	45	32	غير مدعومة	نعم	9

على النقيض من متصفح IE، يدعم Edge هذه الميزة.

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

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