callback

La fonction qui est utilisée pour créer un élément du nouveau tableau. Elle utilise trois arguments :

valeurCourante

La valeur de l'élément du tableau à traiter.

indexFacultatif

L'index de l'élément qui est traité par la fonction.

tableauFacultatif

Le tableau sur lequel on a appelé la méthodemap.

thisArgFacultatif

La valeur à utiliser pourthis lors de l'exécution decallback. La valeur par défaut est l'objet global de l'environnement (Window pour un navigateur).

Un nouveau tableau composé des images de la fonction de rappel.

Lorsqu'on utilisemap, la fonctioncallback fournie en argument est exécutée une fois pour chacun des éléments du tableau, dans l'ordre du tableau. Chaque résultat de l'opération sur un élément sera un élément du nouveau tableau. La fonctioncallback est appelée uniquement pour les indices du tableau pour lesquels il y a des valeurs affectées (y compris si cette valeur estundefined). Si les valeurs ont été supprimées ou qu'elles n'ont jamais été initialisées, la fonction ne sera pas appelée.

callback est appelée avec trois arguments : la valeur de l'élément du tableau, l'index de cet élément et l'objetArray qui est parcouru.

Si le paramètrethisArg est utilisé, il sera utilisé en tant quethis par la fonctioncallback lorsqu'elle sera appelée. S'il n'est pas utilisé, ce sera la valeurundefined qui sera utilisée pour définirthis. La valeurthis finalement prise en compte par la fonctioncallback est définieselon les règles usuelles qui déterminent la valeurthis observée par une fonction.

map ne modifie pas le tableau sur lequel elle est appelée (bien que la fonctioncallback, si elle est appelée, puisse modifier le tableau).

La liste des éléments à traiter lors de l'opérationmap est définie avant le premier appel àcallback. Les éléments qui sont ajoutés au tableau après que l'appel àmap ait été initié ne seront pas traités par la fonctioncallback. Si des éléments ont été modifiés, la valeur utilisée par la fonctioncallback sera celle au moment oùmap est utilisée. Les éléments qui sont supprimés ne sont pas traités. De la même façon, si on appliquemap sur un tableau dont certains éléments sont indéfinis, le résultat possèdera également les mêmes éléments indéfinis.

Dans l'exemple suivant, on crée un tableau composé des racines carrées des éléments d'un premier tableau :

var nombres = [1, 4, 9];var racines = nombres.map(Math.sqrt);// racines vaut désormais [1, 2, 3]// nombres vaut toujours [1, 4, 9]

Ici, on illustre le fonctionnement demap avec une fonction à un argument. Cet argument sera automatiquement remplacé par chaque élément du tableau au fur et à mesure quemap parcourt le tableau :

var nombres = [1, 4, 9];var doubles = nombres.map(function (num) {  return num * 2;});// doubles vaut désormais [2, 8, 18].// nombres vaut toujours [1, 4, 9]

Dans le code qui suit, on utilise un tableau d'objets pour créer un autre tableau contenant de nouveaux objets dans un autre format :

var tableauOrig = [  { clé: 1, valeur: 10 },  { clé: 2, valeur: 20 },  { clé: 3, valeur: 30 },];var tableauFormaté = tableauOrig.map((obj) => {  var rObj = {};  rObj[obj.clé] = obj.valeur;  return rObj;});// tableauFormaté vaut maintenant [{1:10}, {2:20}, {3:30}],// tableauOrig vaut toujours// [{clé:1, valeur:10},//  {clé:2, valeur:20},//  {clé:3, valeur: 30}// ]

Dans cet exemple, on voit comment utiliser la fonctionmap sur une chaîne de caractères pour obtenir un tableau contenant les codes ASCII des valeurs encodées :

var map = Array.prototype.map;var a = map.call("Hello World", function (x) {  return x.charCodeAt(0);});// a vaut désormais [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]

Dans cet exemple, on illustre comment utiliser la méthode map de façon générique, sur un tableau d'objets collectés grâce àquerySelectorAll :

var elems = document.querySelectorAll("select option:checked");var values = Array.prototype.map.call(elems, function (obj) {  return obj.value;});

On aurait également pu utiliser la méthodeArray.from() qui permet de produire un tableau à partir d'un objet itérable.

Exemple inspiré par ce billet (en anglais)

Il est fréquent d'utiliser la fonctioncallback avec un seul argument (l'élément en cours). Certaines fonctions natives sont également souvent appelées avec un unique argument même si elles peuvent prendre en compte plusieurs arguments. En combinant ces deux « habitudes », on peut obtenir certains résultats inattendus :

// Si on utilise :["1", "2", "3"].map(parseInt);// On s'attend à obtenir [1, 2, 3]// Le résultat qu'on obtient est en fait [1, NaN, NaN]// parseInt est souvent utilisé avec un argument mais il// peut être utilisé avec deux arguments// Le premier correspond à l'expression à parser et le second// à la base dans laquelle convertir// Array.prototype.map passe 3 arguments à callback :// l'élément, l'index et le tableau// Le troisième argument sera ignoré par parseInt mais pas le// deuxième, ce qui donnera ce résultat étrangefunction returnInt(element) {  return parseInt(element, 10);}["1", "2", "3"].map(returnInt); // [1, 2, 3]// Le résultat qu'on obtient avec la fonction auxiliaire["1", "2", "3"].map(parseInt); // [1, NaN, NaN]// car map passe trois argument à la fonction et que parseInt// considère le second argument comme base.// En détails :// Premier élément :   "1" à l'indice 0 : parseInt("1",0); donne 1// Deuxième élément :  "2" à l'indice 1 : parseInt("2",1); donne NaN// Troisième élément : "3" à l'indice 2 : parseInt("3",2); donne NaN// Formulation équivalente plus concise avec// une fonction fléchée["1", "2", "3"].map((str) => parseInt(str));// Une autre méthode, plus simple["1", "2", "3"].map(Number); // [1, 2, 3]// à la différence de parseInt, cela fonctionnera pour les// nombres décimaux ou en notation exponentielle["1.1", "2.2e2", "3e300"].map(Number); // [1.1, 220, 3e+300]

• Array.prototype.forEach()
• L'objetMap
• Array.from()