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

<noinclude>{{DISPLAYTITLE:<code>Array.prototype.forEach()‎</code>}}</noinclude>
الدالة <code>Array.prototype.forEach()‎</code> تستدعي دالةً لكل عنصر موجود في المصفوفة.<syntaxhighlight lang="javascript">
const arr = ['a', 'b', 'c'];

arr.forEach(function(element) {
    console.log(element);
});

// a
// b
// c

</syntaxhighlight>

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

</syntaxhighlight>

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

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

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

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

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

=== القيمة المعادة ===
<code>[[JavaScript/undefined|undefined]]</code>.

== الوصف ==
الدالة <code>forEach</code> تُنفِّذ الدالة <code>callback</code> على كل عنصر موجود في المصفوفة. لاحظ أنَّ الدالة <code>callback</code> ستُستدعى على الفهارس التي لها قيمٌ مسندةٌ إليها، فهي لن تستدعى للفهارس التي حُذِفَت أو التي لم تُسنَد إليها قيم.

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

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

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

من غير ممكن إيقاف حلقة تكرار <code>forEach()‎</code> إلا برمي استثناء، وإن كنت تحتاج إلى إيقاف حلقة التكرار فلا يُنصَح باستخدام الدالة <code>forEach()‎</code>، وإنما استخدم حلقات التكرار العادية. إذا أردتَ اختبار قيم المصفوفة فاستخدم الدالة <code>[[JavaScript/Array/every|every()‎]]</code> أو <code>[[JavaScript/Array/some|some()‎]]</code>، ويمكن استخدام الدوال الجديدة <code>[[JavaScript/Array/find|find()‎]]</code> و <code>[[JavaScript/Array/findIndex|findIndex()‎]]</code> لمعرفة وجود قيمة ما.

== أمثلة ==

=== استخدام <code>forEach</code> بدلًا من <code>[[JavaScript/for|for]]</code> ===
استخدام الحلقة <code>[[JavaScript/for|for]]</code> للمرور على عناصر المصفوفة:<syntaxhighlight lang="javascript">
const items = ['item1', 'item2', 'item3'];
const copy = [];

for (let i=0; i<items.length; i++) {
  copy.push(items[i])
}
</syntaxhighlight>استخدام الدالة <code>forEach</code>:<syntaxhighlight lang="javascript">
const items = ['item1', 'item2', 'item3'];
const copy = [];

items.forEach(function(item){
  copy.push(item)
});
</syntaxhighlight>

=== طباعة محتوى مصفوفة ===
الشيفرة الآتية تطبع كل عنصر في المصفوفة في سطر:<syntaxhighlight lang="javascript">
function logArrayElements(element, index, array) {
  console.log('a[' + index + '] = ' + element);
}

// لاحظ أنَّ الفهرس 2 لم يُطبَع لعدم وجود عنصر في المصفوفة في هذا الفهرس
[2, 5, , 9].forEach(logArrayElements);
// a[0] = 2
// a[1] = 5
// a[3] = 9

</syntaxhighlight>

=== استخدام الوسيط <code>thisArg</code> ===
المثال الآتي يُحدِّث خاصيات الكائن من كل عنصر من عناصر المصفوفة:<syntaxhighlight lang="javascript">
function Counter() {
  this.sum = 0;
  this.count = 0;
}
Counter.prototype.add = function(array) {
  array.forEach(function(entry) {
    this.sum += entry;
    ++this.count;
  }, this);
  // ^---- لاحظ هنا
};

const obj = new Counter();
obj.add([2, 5, 9]);
obj.count;
// 3 
obj.sum;
// 16
</syntaxhighlight>

=== تعديل المصفوفة أثناء التكرار ===
المثال الآتي يعرض "one" و "two" و "four"، وعند الوصول إلى العنصر "two" فسيحذَف أوّل عنصر من المصفوفة (باستخدام الدالة <code>[[JavaScript/Array/shift|shift]]</code>)، مما يؤدي إلى تغيير مواضع العناصر البقية (أي أنها ستنتقل إلى الفهرس الذي يسبق موضعها الحالي). ولأنَّ العنصر "four" أصبح في الفهرس الذي يسبقه فسيتم تجاوز العنصر "three"؛ لاحظ أنَّ الدالة <code>forEach</code> لا تنسخ المصفوفة قبل بدء الدوران على عناصرها:<syntaxhighlight lang="javascript">
var words = ['one', 'two', 'three', 'four'];
words.forEach(function(word) {
  console.log(word);
  if (word === 'two') {
    words.shift();
  }
});
// one
// two
// four
</syntaxhighlight>

== تعويض نقص دعم المتصفحات ==
أضيفت هذه الدالة في الإصدار الخامس من معيار ECMAScript، لذا يمكنك استخدام الشيفرة الآتية لإضافتها للمتصفحات التي لا تدعمها:<syntaxhighlight lang="javascript">
// Production steps of ECMA-262, Edition 5, 15.4.4.18
// Reference: http://es5.github.io/#x15.4.4.18
if (!Array.prototype.forEach) {

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

    var T, 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 k be 0.
    k = 0;

    // 7. Repeat while k < len.
    while (k < len) {

      var kValue;

      // 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. Call the Call internal method of callback with T as
        // the this value and argument list containing kValue, k, and O.
        callback.call(T, kValue, k, O);
      }
      // d. Increase k by 1.
      k++;
    }
    // 8. return undefined.
  };
}

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|نعم
|نعم
|9
|نعم
|نعم
|}
== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-array.prototype.foreach ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.foreach ECMAScript 2015 (6th Edition)]‎.
* معيار [http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.18 ECMAScript 5.1]. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Array|{{SUBPAGENAME}}]]