Array : mthode forEach()

Exemple interactif

const array = ["a", "b", "c"];

array.forEach((element) => console.log(element));

// Sortie attendue : "a"
// Sortie attendue : "b"
// Sortie attendue : "c"

Syntaxe

forEach(callbackFn)
forEach(callbackFn, thisArg)

Paramtres

callbackFn

La fonction excuter pour chaque lment du tableau. Sa valeur de retour est ignore. La fonction est appele avec les arguments suivants :

element

L'lment en cours de traitement dans le tableau.

index

L'indice de l'lment en cours de traitement dans le tableau.

array

Le tableau sur lequel la mthode forEach() a t appele.

thisArg Facultatif

La valeur utiliser comme this lors de l'excution de la fonction callbackFn. Voir les mthodes itratives.

Valeur de retour

Aucune (undefined).

Description

La mthode forEach() est une mthode itrative. Elle appelle la fonction callbackFn fournie une fois pour chaque lment du tableau, dans l'ordre croissant des indices. Contrairement map(), forEach() retourne toujours undefined et ne peut pas tre chane. L'usage typique est d'excuter des effets de bord la fin d'une chane de caractres. Consultez la section mthodes itratives pour plus d'informations sur le fonctionnement gnral de ces mthodes.

La fonction callbackFn est appele uniquement pour les indices du tableau qui ont une valeur attribue. Elle n'est pas appele pour les cases vides dans un tableau creux.

La mthode forEach() est gnrique. Elle attend seulement que la valeur de this possde une proprit length et des proprits cls entires.

Il n'existe aucun moyen d'arrter ou de sortir d'une boucle forEach() autrement qu'en lanant une exception. Si vous avez besoin de ce comportement, la mthode forEach() n'est pas adapte.

L'arrt anticip peut tre ralis avec des instructions de boucle comme for, for...of et for...in. Les mthodes de tableau comme every(), some(), find(), et findIndex() arrtent aussi l'itration ds que ce n'est plus ncessaire.

forEach() attend une fonction synchrone elle n'attend pas les promesses. Veillez bien comprendre les implications de l'utilisation de promesses (ou de fonctions asynchrones) comme fonctions de rappel de forEach.

const notes = [5, 4, 5];
let somme = 0;

const fonctionSommeAsync = async (a, b) => a + b;

notes.forEach(async (note) => {
  somme = await fonctionSommeAsync(somme, note);
});

console.log(somme);
// Sortie attendue : 14
// Sortie relle : 0

Pour excuter une srie d'oprations asynchrones squentiellement ou en concurrence, voir la section composition de promesses.

Exemples

Conversion d'une boucle for en forEach

const elements = ["lment 1", "lment 2", "lment 3"];
const elementsCopie = [];

// avant
for (let i = 0; i < elements.length; i++) {
  elementsCopie.push(elements[i]);
}

// aprs
elements.forEach((element) => {
  elementsCopie.push(element);
});

Afficher le contenu d'un tableau

Le code suivant affiche une ligne pour chaque lment d'un tableau :

const logArrayElements = (element, index /*, array */) => {
  console.log(`a[${index}] = ${element}`);
};

// Remarquez que l'indice 2 est ignor, car il n'y a pas d'lment  cette position dans le tableau.
[2, 5, , 9].forEach(logArrayElements);
// Affiche :
// a[0] = 2
// a[1] = 5
// a[3] = 9

Utilisation de thisArg

L'exemple (artificiel) suivant met jour les proprits d'un objet partir de chaque entre du tableau :

class Compteur {
  constructor() {
    this.somme = 0;
    this.compte = 0;
  }
  ajouter(tableau) {
    // Seules les expressions de fonction possdent leur propre liaison this.
    tableau.forEach(function compterEntree(entree) {
      this.somme += entree;
      ++this.compte;
    }, this);
  }
}

const obj = new Compteur();
obj.ajouter([2, 5, 9]);
console.log(obj.compte); // 3
console.log(obj.somme); // 16

Puisque le paramtre thisArg (this) est fourni forEach(), il est transmis callback chaque appel. La fonction de rappel l'utilise comme valeur de this.

Fonction de copie d'objet

Le code suivant cre une copie d'un objet donn.

Il existe diffrentes manires de copier un objet. Ce qui suit n'est qu'une faon de faire et est prsent pour expliquer le fonctionnement de Array.prototype.forEach() en utilisant les fonctions utilitaires Object.*.

const copie = (objet) => {
  const copie = Object.create(Object.getPrototypeOf(objet));
  const nomsProp = Object.getOwnPropertyNames(objet);
  nomsProp.forEach((nom) => {
    const desc = Object.getOwnPropertyDescriptor(objet, nom);
    Object.defineProperty(copie, nom, desc);
  });
  return copie;
};

const obj1 = { a: 1, b: 2 };
const obj2 = copie(obj1); // obj2 est identique  obj1 maintenant

Aplatir un tableau

L'exemple suivant est uniquement prsent des fins d'apprentissage. Si vous souhaitez aplatir un tableau en utilisant des mthodes intgres, vous pouvez utiliser Array.prototype.flat().

const aplatir = (arr) => {
  const resultat = [];
  arr.forEach((item) => {
    if (Array.isArray(item)) {
      resultat.push(...aplatir(item));
    } else {
      resultat.push(item);
    }
  });
  return resultat;
};

// Utilisation
const imbrique = [1, 2, 3, [4, 5, [6, 7], 8, 9]];
console.log(aplatir(imbrique)); // [1, 2, 3, 4, 5, 6, 7, 8, 9]

Utilisation du troisime argument de callbackFn

L'argument array est utile si vous souhaitez accder un autre lment du tableau, en particulier lorsque vous n'avez pas de variable existante qui fait rfrence au tableau. L'exemple suivant utilise d'abord filter() pour extraire les valeurs positives, puis utilise forEach() pour afficher ses voisins.

const nombres = [3, -1, 1, 4, 1, 5];
nombres
  .filter((num) => num > 0)
  .forEach((num, idx, arr) => {
    // Sans l'argument arr, il n'y a aucun moyen d'accder facilement au tableau intermdiaire sans le stocker dans une variable.
    console.log(arr[idx - 1], num, arr[idx + 1]);
  });
// undefined 3 1
// 3 1 4
// 1 4 1
// 4 1 5
// 1 5 undefined

Utilisation de forEach() sur les tableaux creux

const tableauCreux = [1, 3, /* vide */, 7];
let nombreAppelsCallback = 0;

tableauCreux.forEach((element) => {
  console.log({ element });
  nombreAppelsCallback++;
});

console.log({ nombreAppelsCallback });

// { element: 1 }
// { element: 3 }
// { element: 7 }
// { nombreAppelsCallback: 3 }

La fonction de rappel n'est pas appele pour la valeur manquante l'indice 2.

Appel de forEach() sur des objets ressemblant des tableaux

La mthode forEach() lit la proprit length de this puis accde chaque proprit dont la cl est un entier non ngatif infrieur length.

const objetSimilaireTableau = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 5, // ignor par forEach(), car length vaut 3
};
Array.prototype.forEach.call(objetSimilaireTableau, (x) => console.log(x));
// 2
// 3
// 4

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet global Array
• La mthode Array.prototype.find()
• La mthode Array.prototype.map()
• La mthode Array.prototype.filter()
• La mthode Array.prototype.every()
• La mthode Array.prototype.some()
• La mthode TypedArray.prototype.forEach()
• La mthode Map.prototype.forEach()
• La mthode Set.prototype.forEach()
• Prothse d'mulation de Array.prototype.forEach dans core-js (angl.)
• Prothse d'mulation es-shims de Array.prototype.forEach (angl.)