La méthodeunshift() des instances deArray ajoute les éléments définis au début d'un tableau et retourne la nouvelle longueur du tableau.

Exemple interactif

const array1 = [1, 2, 3];console.log(array1.unshift(4, 5));// Résultat attendu : 5console.log(array1);// Résultat attendu : Array [4, 5, 1, 2, 3]

Syntaxe

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

Paramètres

element1, …,elementN

Les éléments à ajouter au début du tableauarr.

Valeur de retour

La nouvelle valeur de la propriétélength du tableau sur lequel a été appelée la méthode.

Description

La méthodeunshift() insère les valeurs fournies au début d'un objet ressemblant à un tableau.

La méthodeArray.prototype.push() a un comportement similaire àunshift(), mais s'applique à la fin d'un tableau.

Veuillez noter que, si plusieurs éléments sont passés en paramètres, ils sont insérés en bloc au début de l'objet, dans le même ordre que celui dans lequel ils ont été passés en paramètres. Ainsi, appelerunshift() avecn argumentsune fois, ou l'appelern fois avec1 argument (par exemple dans une boucle), ne donne pas le même résultat.

Exemple :

let arr = [4, 5, 6];arr.unshift(1, 2, 3);console.log(arr);// [1, 2, 3, 4, 5, 6]arr = [4, 5, 6]; // réinitialisation du tableauarr.unshift(1);arr.unshift(2);arr.unshift(3);console.log(arr);// [3, 2, 1, 4, 5, 6]

La méthodeunshift() estgénérique. Elle attend seulement que la valeur dethis possède une propriétélength et des propriétés à indices entiers. Bien qu'une chaîne de caractères soit aussi un objet ressemblant à un tableau, cette méthode ne convient pas pour être appliquée sur une chaîne de caractères, car elle est immuable.

Exemples

Utilisation deunshift()

const arr = [1, 2];arr.unshift(0); // le résultat de l'appel est 3, qui est la nouvelle longueur du tableau// arr vaut [0, 1, 2]arr.unshift(-2, -1); // la nouvelle longueur du tableau est 5// arr vaut [-2, -1, 0, 1, 2]arr.unshift([-4, -3]); // la nouvelle longueur du tableau est 6// arr vaut [[-4, -3], -2, -1, 0, 1, 2]arr.unshift([-7, -6], [-5]); // la nouvelle longueur du tableau est 8// arr vaut [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

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

La méthodeunshift() lit la propriétélength dethis. Elle décale tous les indices dans la plage de0 àlength - 1 vers la droite du nombre d'arguments (en incrémentant leurs valeurs de ce nombre). Ensuite, elle définit chaque indice à partir de0 avec les arguments passés àunshift(). Enfin, elle définit la propriétélength à l'ancienne longueur plus le nombre d'éléments ajoutés au début.

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

Spécifications

Compatibilité des navigateurs

Voir aussi

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