عرض مصدر JavaScript/Array/findIndex

<noinclude>{{DISPLAYTITLE:<code>Array.prototype.findIndex()‎</code>}}</noinclude>
الدالة <code>Array.prototype.findIndex()‎</code> تُعيد '''فهرس''' أوّل عنصر في المصفوفة الذي يُطابِق الشرط الموجود في دالة الاختبار؛ وإلا ستُعاد القيمة <code>-1</code>.<syntaxhighlight lang="javascript">
var array1 = [5, 12, 8, 130, 44];

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

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

</syntaxhighlight>انظر أيضًا إلى صفحة الدالة <code>[[JavaScript/Array/find|find()‎]]</code> التي تُعيد '''قيمة''' العنصر الذي عُثِر عليه في المصفوفة بدلًا من فهرسه؛ أما إذا أردتَ معرفة موضع عنصر مُحدَّد فانظر إلى الدالة <code>[[JavaScript/Array/indexOf|indexOf()‎]]</code>، وإذا شئت تحديد إن كان العنصر موجودًا ضمن المصفوفة فاستعمل الدالة <code>[[JavaScript/Array/includes|includes()‎]]</code>.

== البنية العامة ==
<syntaxhighlight lang="javascript">
arr.findIndex(callback[, thisArg])

</syntaxhighlight>

=== <code>callback</code> ===
الدالة التي ستختبر كل عنصر من عناصر المصفوفة، وتقبل ثلاثة وسائط.

==== <code>currentValue</code> ====
العنصر الحالي الذي يُعالِج في المصفوفة، وهذه القيمة مطلوبة.

==== <code>index</code> ====
فهرس العنصر الحالي في المصفوفة، وهذه القيمة اختيارية.

==== <code>array</code> ====
المصفوفة التي استدعيت الدالة <code>findIndex</code> عليها، وهذه القيمة اختيارية.

=== <code>thisArg</code> ===
القيمة التي ستُستخدَم في <code>this</code> عند استدعاء الدالة <code>callback</code>، وهي قيمة اختيارية.

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

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

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

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

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

== أمثلة ==

=== العثور على فهرس عدد أوليّ في مصفوفة ===
<syntaxhighlight lang="javascript">
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

</syntaxhighlight>

== تعويض نقص دعم المتصفحات ==
أضيفت هذه الدالة في معيار ECMAScript 2015 (أي ES6)، لذا يمكنك استخدام الشيفرة الآتية لإضافتها للمتصفحات التي لا تدعمها:<syntaxhighlight lang="javascript">
// 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;
    }
  });
}

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|45
|25
|غير مدعومة
|32
|8
|}
على النقيض من متصفح IE، يدعم Edge هذه الميزة.

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-array.prototype.findIndex ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.findindex ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Array|{{SUBPAGENAME}}]]