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

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

構文

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)

 

戻り値

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 がそれらを参照した時点での値になります。削除された配列要素を参照することはありません。既に参照された配列要素がイテレーションの間に削除された場合 (e.g. shift()を適用)、後の要素は飛ばされます。

forEach が配列の各要素に対して callback 関数を一度実行します。 map()reduce() と異なり、常に undefined を返しチェーンできません。チェーンの最後に副作用を生じさせるのが典型的な使用法です。

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 の定義
ドラフト  

ブラウザ実装状況

Update compatibility data on GitHub
デスクトップモバイルサーバー
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeEdge MobileAndroid 版 FirefoxAndroid 版 OperaiOS 版 SafariSamsung InternetNode.js
基本対応Chrome 完全対応 ありEdge 完全対応 ありFirefox 完全対応 1.5IE 完全対応 9Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありEdge Mobile 完全対応 ありFirefox Android 完全対応 4Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 ありnodejs 完全対応 あり

凡例

完全対応  
完全対応

See also

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

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