La méthodeflatMap() des instances deArray retourne un nouveau tableau créé en appliquant une fonction de rappel à chaque élément du tableau, puis en aplatissant le résultat d'un niveau. Elle est identique à unemap() suivi d'unflat() de profondeur 1 (arr.map(...args).flat()), mais légèrement plus efficace que d'appeler ces deux méthodes séparément.

Exemple interactif

const arr = [1, 2, 1];const result = arr.flatMap((num) => (num === 2 ? [2, 2] : 1));console.log(result);// sortie attendue : Array [1, 2, 2, 1]

Syntaxe

flatMap(callbackFn)flatMap(callbackFn, thisArg)

Paramètres

callbackFn

La fonction à exécuter pour chaque élément du tableau. Elle doit retourner un tableau contenant les nouveaux éléments du nouveau tableau, ou une seule valeur qui n'est pas un tableau à ajouter au nouveau tableau. La fonction est appelée avec les arguments suivants :

element

L'élément en cours de traitement dans le tableau.

index

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

array

Le tableau sur lequelflatMap() a été appelée.

thisArgFacultatif

La valeur à utiliser commethis lors de l'exécution decallbackFn. Voirles méthodes itératives.

Valeur de retour

Un nouveau tableau avec chaque élément étant le résultat de la fonction de rappel (callback en anglais) et aplati d'un niveau.

Description

La méthodeflatMap() est uneméthode itérative. VoirArray.prototype.map() pour une description détaillée de la fonction de rappel. La méthodeflatMap() est identique àmap(callbackFn, thisArg) suivie deflat(1) : pour chaque élément, elle produit un tableau de nouveaux éléments et concatène les tableaux résultants pour former un nouveau tableau. Lire la sectionméthodes itératives pour plus d'informations sur le fonctionnement général de ces méthodes.

La méthodeflatMap() estgénérique. Elle attend seulement que la valeur dethis possède une propriétélength et des propriétés à clés entières. Cependant, la valeur retournée parcallbackFn doit être un tableau pour être aplatie.

Alternative

Pré-allouer et itérer explicitement

const arr = [1, 2, 3, 4];arr.flatMap((x) => [x, x * 2]);// est équivalent àconst n = arr.length;const acc = new Array(n * 2);for (let i = 0; i < n; i++) {  const x = arr[i];  acc[i * 2] = x;  acc[i * 2 + 1] = x * 2;}// [1, 2, 2, 4, 3, 6, 4, 8]

Notez que dans ce cas particulier, l'approche avecflatMap est plus lente que l'approche avec une boucle for — en raison de la création de tableaux temporaires qui doivent être collectés par le ramasse-miettes, et parce que le tableau retourné n'a pas besoin d'être redimensionné fréquemment. Cependant,flatMap peut rester la solution appropriée dans les cas où sa flexibilité et sa lisibilité sont souhaitées.

Exemples

map() etflatMap()

var arr1 = [1, 2, 3, 4];arr1.map((x) => [x * 2]);// [[2], [4], [6], [8]]arr1.flatMap((x) => [x * 2]);// [2, 4, 6, 8]// seul un niveau est aplatiarr1.flatMap((x) => [[x * 2]]);// [[2], [4], [6], [8]]

Bien que ce qui précède aurait pu être obtenu en utilisant simplementmap, voici un exemple qui met mieux en valeur l'utilisation deflatMap().

Générons une liste de mots à partir d'une liste de phrases.

let tableau = ["Coucou comment", "", "ça va ?"];tableau.map((x) => x.split(" "));// [["Coucou", "comment"], [""], ["ça", "va", "?"]]tableau.flatMap((x) => x.split(" "));// ["Coucou", "comment", "", "ça", "va", "?"]

On notera que la longueur de la liste obtenue avecflatMap est différente de la longueur de la liste originale.

Ajouter et supprimer des éléments lors d'unmap()

flatMap peut être utilisé pour ajouter et supprimer des éléments (modifier le nombre d'éléments) lors d'unmap. Autrement dit, cela permet de faire correspondreplusieurs éléments à plusieurs éléments (en traitant chaque élément d'entrée séparément), plutôt que toujoursun-à-un. En ce sens, cela fonctionne comme l'opposé defilter. Retournez un tableau à 1 élément pour conserver l'élément, un tableau à plusieurs éléments pour en ajouter, ou un tableau à 0 élément pour le supprimer.

// Supposons que nous voulons supprimer tous les nombres négatifs// et découper les nombres impairs en un nombre pair et un 1const a = [5, 4, -3, 20, 17, -33, -4, 18];//         |\  \  x   |  | \   x   x   |//        [4,1, 4,   20, 16, 1,       18]const resultat = a.flatMap((n) => {  if (n < 0) {    return [];  }  return n % 2 === 0 ? [n] : [n - 1, 1];});console.log(resultat); // [4, 1, 4, 20, 16, 1, 18]

Utiliser le troisième argument decallbackFn

L'argumentarray est utile si vous souhaitez accéder à un autre élément du tableau, en particulier lorsque vous n'avez pas de variable existante qui fait référence au tableau. L'exemple suivant utilise d'abordfilter() pour extraire les stations en service puis utiliseflatMap() pour créer un nouveau tableau où chaque élément contient une station et la station suivante. Pour la dernière station, il retourne un tableau vide afin de l'exclure du tableau final.

const stations = ["New Haven", "West Haven", "Milford (fermé)", "Stratford"];const line = stations  .filter((name) => !name.endsWith("(fermé)"))  .flatMap((name, idx, arr) => {    // Sans l'argument arr, il n'y a aucun moyen d'accéder facilement    // au tableau intermédiaire sans le stocker dans une variable.    if (idx === arr.length - 1) return []; // la dernière station n'a pas de suivante    return [`${name} - ${arr[idx + 1]}`];  });console.log(line); // ['New Haven - West Haven', 'West Haven - Stratford']

L'argumentarray n'estpas le tableau en cours de construction — il n'existe aucun moyen d'accéder au tableau en cours de construction depuis la fonction de rappel.

UtiliserflatMap() sur des tableaux creux

callbackFn ne sera pas appelée pour les trous dans le tableau source carmap() ne le fait pas, tandis queflat() ignore les trous dans les tableaux retournés.

console.log([1, 2, , 4, 5].flatMap((x) => [x, x * 2])); // [1, 2, 2, 4, 4, 8, 5, 10]console.log([1, 2, 3, 4].flatMap((x) => [, x * 2])); // [2, 4, 6, 8]

AppelerflatMap() sur des objets qui ne sont pas des tableaux

La méthodeflatMap() lit la propriétélength dethis puis accède à chaque propriété dont la clé est un entier non négatif inférieur àlength. Si la valeur de retour de la fonction de rappel n'est pas un tableau, elle est toujours ajoutée directement au tableau résultat.

const objetSimilaireTableau = {  length: 3,  0: 1,  1: 2,  2: 3,  3: 4, // ignoré par flatMap() car length vaut 3};console.log(  Array.prototype.flatMap.call(objetSimilaireTableau, (x) => [x, x * 2]),);// [1, 2, 2, 4, 3, 6]// Les objets de type tableau retournés par la fonction de rappel ne seront pas aplatísconsole.log(  Array.prototype.flatMap.call(objetSimilaireTableau, (x) => ({    length: 1,    0: x,  })),);// [ { '0': 1, length: 1 }, { '0': 2, length: 1 }, { '0': 3, length: 1 } ]

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• L'objet globalArray
• La méthodeArray.prototype.concat()
• La méthodeArray.prototype.flat()
• La méthodeArray.prototype.map()
• La méthodeArray.prototype.reduce()
• Prothèse d'émulation deArray.prototype.flatMap dans core‑js^(angl.)
• Prothèse d'émulation deArray.prototype.flatMap dans es‑shims^(angl.)