JavaScript/Array/findIndex

الدالة Array.prototype.findIndex()‎ تُعيد فهرس أوّل عنصر في المصفوفة الذي يُطابِق الشرط الموجود في دالة الاختبار؛ وإلا ستُعاد القيمة -1.

var array1 = [5, 12, 8, 130, 44];

function findFirstLargeNumber(element) {
  return element > 13;
}

console.log(array1.findIndex(findFirstLargeNumber)); // 3

انظر أيضًا إلى صفحة الدالة find()‎ التي تُعيد قيمة العنصر الذي عُثِر عليه في المصفوفة بدلًا من فهرسه؛ أما إذا أردتَ معرفة موضع عنصر مُحدَّد فانظر إلى الدالة indexOf()‎، وإذا شئت تحديد إن كان العنصر موجودًا ضمن المصفوفة فاستعمل الدالة includes()‎.

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

arr.findIndex(callback[, thisArg])

callback

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

currentValue

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

index

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

array

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

thisArg

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

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

فهرس أوّل قيمة تجتاز دالة الاختبار في المصفوفة، وإن لم تكن موجودةً فستُعاد القيمة -1.

الوصف

الدالة findIndex تُنفِّذ الدالة callback في كل عنصر موجود في المصفوفة حتى تجد عنصرًا يُعيد القيمة true من الدالة callback، فعند وجود ذلك العنصر فستُعيد الدالة findIndex فهرس ذاك العنصر؛ وإذا لم يُعثر على ذاك العنصر، فستُعيد الدالة findIndex القيمة -1. لاحظ أنَّ الدالة callback ستُستدعى على الفهارس من 0 إلى length -1 وليس على الفهارس لها قيمٌ مسندةٌ إليها، وهذا يعني أنَّ هذه الدالة أقل كفاءةً من الدوال الأخرى التي لا تختبر إلا الفهارس المرتبطة بقيم.

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

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

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

أمثلة

العثور على فهرس عدد أوليّ في مصفوفة

function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}

console.log([4, 6, 8, 12].findIndex(isPrime)); // -1 لم يعُثَر على قيمة
console.log([4, 6, 7, 12].findIndex(isPrime)); // 2

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

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

// https://tc39.github.io/ecma262/#sec-array.prototype.findIndex
if (!Array.prototype.findIndex) {
  Object.defineProperty(Array.prototype, 'findIndex', {
    value: function(predicate) {
     // 1. Let O be ? ToObject(this value).
      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If IsCallable(predicate) is false, throw a TypeError exception.
      if (typeof predicate !== 'function') {
        throw new TypeError('predicate must be a function');
      }

      // 4. If thisArg was supplied, let T be thisArg; else let T be undefined.
      var thisArg = arguments[1];

      // 5. Let k be 0.
      var k = 0;

      // 6. Repeat, while k < len
      while (k < len) {
        // a. Let Pk be ! ToString(k).
        // b. Let kValue be ? Get(O, Pk).
        // c. Let testResult be ToBoolean(? Call(predicate, T, « kValue, k, O »)).
        // d. If testResult is true, return k.
        var kValue = o[k];
        if (predicate.call(thisArg, kValue, k, o)) {
          return k;
        }
        // e. Increase k by 1.
        k++;
      }

      // 7. Return -1.
      return -1;
    }
  });
}

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

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

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

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

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