La méthodepush() des instancesArray ajoute les éléments définis à la fin d'un tableau et retourne la nouvelle longueur du tableau.

Exemple interactif

const animals = ["cochons", "chèvres", "moutons"];const count = animals.push("vaches");console.log(count);// Résultat attendu : 4console.log(animals);// Résultat attendu : Array ["cochons", "chèvres", "moutons", "vaches"]animals.push("poules", "chats", "chiens");console.log(animals);// Résultat attendu : Array ["cochons", "chèvres", "moutons", "vaches", "poules", "chats", "chiens"]

Syntaxe

push()push(element1)push(element1, element2)push(element1, element2, /* …, */ elementN)

Paramètres

element1, …,elementN

Les éléments à ajouter à la fin du tableau.

Valeur de retour

La nouvelle propriétélength de l'objet sur lequel la méthode a été appelée.

Description

La méthodepush() ajoute des valeurs à un tableau.

Array.prototype.unshift() a un comportement similaire àpush(), mais appliqué au début d'un tableau.

La méthodepush() est uneméthode de mutation. Elle modifie la longueur et le contenu dethis. Si vous souhaitez que la valeur dethis reste identique mais retourner un nouveau tableau avec des éléments ajoutés à la fin, vous pouvez utiliserarr.concat([element0, element1, /* ... ,*/ elementN]) à la place. Remarquez que les éléments sont placés dans un tableau supplémentaire — sinon, si l'élément est lui-même un tableau, il serait décomposé au lieu d'être ajouté comme un seul élément à cause du comportement deconcat().

La méthodepush() 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. Bien que les chaînes de caractères ressemblent aussi à des tableaux, cette méthode ne leur convient pas car elles sont immuables.

Exemples

Ajouter des éléments à un tableau

Le code suivant crée un tableausports contenant deux éléments, puis ajoute deux éléments supplémentaires. La variabletotal contient la nouvelle longueur du tableau.

const sports = ["football", "baseball"];const total = sports.push("tennis", "natation");console.log(sports); // ['football', 'baseball', 'tennis', 'natation']console.log(total); // 4

Fusionner deux tableaux

Cet exemple utilise lasyntaxe de décomposition pour ajouter tous les éléments d'un second tableau au premier.

const legumes = ["panais", "pomme de terre"];const autresLegumes = ["céleri", "betterave"];// On fusionne le second tableau dans le premierlegumes.push(...autresLegumes);console.log(legumes); // ['panais', 'pomme de terre', 'céleri', 'betterave']

La fusion de deux tableaux peut aussi se faire avec la méthodeconcat().

Appelerpush() sur des objets non tableaux

La méthodepush() lit la propriétélength dethis. Elle définit ensuite chaque index dethis à partir delength avec les arguments passés àpush(). Enfin, elle définit la propriétélength à l'ancienne valeur plus le nombre d'éléments ajoutés.

const objetSimilaireTableau = {  length: 3,  sansRapport: "toto",  2: 4,};Array.prototype.push.call(objetSimilaireTableau, 1, 2);console.log(objetSimilaireTableau);// { '2': 4, '3': 1, '4': 2, length: 5, sansRapport: 'toto' }const objetSimple = {};// Il n'y a pas de propriété length, donc la longueur est 0Array.prototype.push.call(objetSimple, 1, 2);console.log(objetSimple);// { '0': 1, '1': 2, length: 2 }

Utiliser un objet comme un tableau

Comme mentionné précédemment,push est volontairement générique, ce qui peut être utilisé à notre avantage.Array.prototype.push fonctionne très bien sur un objet, comme le montre cet exemple.

Notez que nous ne créons pas un tableau pour stocker une collection d'objets. À la place, nous stockons la collection sur l'objet lui-même et utilisonscall surArray.prototype.push pour faire croire à la méthode que nous manipulons un tableau — et cela fonctionne, grâce à la façon dont JavaScript permet d'établir le contexte d'exécution comme on le souhaite.

const obj = {  length: 0,  ajoutElem(elem) {    // obj.length est automatiquement incrémenté    // à chaque ajout d'un élément.    [].push.call(this, elem);  },};// Ajoutons quelques objets vides pour illustrer.obj.ajoutElem({});obj.ajoutElem({});console.log(obj.length); // 2

Notez que même siobj n'est pas un tableau, la méthodepush a bien incrémenté la propriétélength deobj comme si nous manipulions un véritable tableau.

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• L'objet globalArray
• La méthodeArray.prototype.pop()
• La méthodeArray.prototype.shift()
• La méthodeArray.prototype.unshift()
• La méthodeArray.prototype.concat()
• La méthodeArray.prototype.splice()
• Prothèse d'émulation deArray.prototype.push danscore-js avec corrections de cette méthode^(angl.)
• Prothèse d'émulation es-shims deArray.prototype.push^(angl.)