この翻訳は不完全です。英語から この記事を翻訳 してください。

与えられた関数を、配列の各要素に対して一度ずつ実行します。

構文

arr.forEach(function callback(currentValue[, index[, array]]) {
    //your iterator
}[, thisArg]);

引数

callback
各要素に対して実行するコールバック関数で、3つの引数をとります。
currentValue
現在処理されている配列の要素
indexOptional
現在処理されている配列の要素のインデックス
arrayOptional
forEachが適用されている配列
thisArg Optional

callback 内で this として使用する値 (i.e the reference Object)

Return value

undefined.

説明

forEach() は、与えられた関数 (callback)を配列に含まれる各要素に対して一度ずつ、昇順で呼び出します。すでに削除されたインデックスや、まだ値が代入されていないインデックスに対しては呼び出されません。 (i.e. on sparse arrays)

callback は次の 3つの引数 で呼び出されます:

  • 要素の値
  • 要素のインデックス
  • 走査されている配列

forEachthisArg パラメータが与えられると、callback の呼び出し時にそのオブジェクトが this として使用されます。thisArg が与えられなかった場合は、undefined が使われますが、callback 内で実際に観測出来る thisthe usual rules for determining the this seen by a function に従います。

forEach によって処理される配列要素の範囲は、callback が最初に呼び出される前に設定されます。forEach の呼び出しが開始された後に追加された配列要素に対しては、callback は実行されません。既存の配列要素が変更または削除された場合、callback に渡される値は forEach がそれらを参照した時点での値になります。削除された配列要素を参照することはありません。If elements that are already visited are removed (e.g. using shift()) during the iteration, later elements will be skipped - see example below.

forEach() executes the callback function once for each array element; unlike map() or reduce() it always returns the value undefined and is not chainable. The typical use case is to execute side effects at the end of a chain.

forEach() は呼び出された配列を変化させません。

There is no way to stop or break a forEach() loop other than by throwing an exception. If you need such behavior, the forEach() method is the wrong tool.

Early termination may be accomplished with:

The other Array methods: every()some()find(), and findIndex() test the array elements with a predicate returning a truthy value to determine if further iteration is required.

Converting a for loop to forEach

before

const items = ['item1', 'item2', 'item3'];
const copy = [];

for (let i=0; i<items.length; i++) {
  copy.push(items[i])
}

after

const items = ['item1', 'item2', 'item3'];
const copy = [];

items.forEach(function(item){
  copy.push(item)
});

 

配列の内容を出力する

次のコードは配列の要素毎に、コンソールに 1 行ずつ要素の内容を出力します。

function logArrayElements(element, index, array) {
  console.log('a[' + index + '] = ' + element);
}

// Notice that index 2 is skipped since there is no item at
// that position in the array.
[2, 5, , 9].forEach(logArrayElements);
// logs:
// a[0] = 2
// a[1] = 5
// a[3] = 9

Using thisArg

The following (contrived) example updates an object's properties from each entry in the array:

function Counter() {
  this.sum = 0;
  this.count = 0;
}
Counter.prototype.add = function(array) {
  array.forEach(function(entry) {
    this.sum += entry;
    ++this.count;
  }, this);
  // ^---- Note
};

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

Since the thisArg parameter (this) is provided to forEach(), it is passed to callback each time it's invoked, for use as its this value.

If passing the function argument using an arrow function expression the thisArg parameter can be omitted as arrow functions lexically bind the this value.

オブジェクトをコピーする関数

次のコードは与えられたオブジェクトのコピーを生成します。オブジェクトのコピーを生成するには他にもいくつか方法がありますが、ここでは Array.prototype.forEach の動作を説明する為に、forEach を選択しています。またここでは、ECMA-262 第 5 版で新たに仕様に追加されたオブジェクトのメソッドを使用しているという点に留意して下さい。

function copy(obj) {
  const copy = Object.create(Object.getPrototypeOf(obj));
  const propNames = Object.getOwnPropertyNames(obj);

  propNames.forEach(function(name) {
    const desc = Object.getOwnPropertyDescriptor(obj, name);
    Object.defineProperty(copy, name, desc);
  });

  return copy;
}

const obj1 = { a: 1, b: 2 };
const obj2 = copy(obj1); // obj2 looks like obj1 now

If the array is modified during iteration, other elements might be skipped.

The following example logs "one", "two", "four". When the entry containing the value "two" is reached, the first entry of the whole array is shifted off, which results in all remaining entries moving up one position. Because element "four" is now at an earlier position in the array, "three" will be skipped. forEach() does not make a copy of the array before iterating.

var words = ['one', 'two', 'three', 'four'];
words.forEach(function(word) {
  console.log(word);
  if (word === 'two') {
    words.shift();
  }
});
// one
// two
// four

互換性

forEach は ECMA-262 標準への最近の追加であり、他の版の標準実装には存在しない場合があります。次のコードをスクリプトの先頭に記述する事により、forEach がネイティブでサポートされていない環境でもこれを使用する事が可能となります。これは ECMA-262 第 5 版で定められたアルゴリズムと全く同じものです。ObjectTypeError はそれぞれオリジナルの値を持ち、またそれらの callback.callFunction.prototype.call のオリジナルの値として評価されます。

// 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.
  };
}

Specifications

Specification Status Comment
ECMAScript 5.1 (ECMA-262)
Array.prototype.forEach の定義
標準 Initial definition. Implemented in JavaScript 1.6.
ECMAScript 2015 (6th Edition, ECMA-262)
Array.prototype.forEach の定義
標準  
ECMAScript Latest Draft (ECMA-262)
Array.prototype.forEach の定義
ドラフト  

ブラウザ実装状況

機能ChromeEdgeFirefoxInternet ExplorerOperaSafari
基本対応 あり あり1.59 あり あり
機能Android webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
基本対応 あり あり あり4 あり あり あり

See also

ドキュメントのタグと貢献者

このページの貢献者: woodmix, axion014, dlwe, kkas, teoli, ethertank, Potappo, Shoot
最終更新者: woodmix,