Array.prototype.unshift()

Probieren Sie es aus

const array = [1, 2, 3];

console.log(array.unshift(4, 5));
// Expected output: 5

console.log(array);
// Expected output: Array [4, 5, 1, 2, 3]

Syntax

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

Parameter

element1, …, elementN

Die Elemente, die am Anfang von arr eingefügt werden sollen.

Rückgabewert

Der neue Wert der Eigenschaft length des Objekts, für das die Methode aufgerufen wurde.

Beschreibung

Die Methode unshift() fügt die angegebenen Werte am Anfang eines array-ähnlichen Objekts ein.

Array.prototype.push() verhält sich ähnlich wie unshift(), fügt die Werte jedoch am Ende eines Arrays ein.

Wenn mehrere Elemente als Parameter übergeben werden, werden sie als Gruppe am Anfang des Objekts eingefügt – in genau der Reihenfolge, in der sie übergeben wurden. Daher führen ein einmaliger Aufruf von unshift() mit n Argumenten und n Aufrufe mit jeweils 1 Argument (beispielsweise in einer Schleife) nicht zum selben Ergebnis.

Das folgende Beispiel zeigt den Unterschied:

let arr = [4, 5, 6];

arr.unshift(1, 2, 3);
console.log(arr);
// [1, 2, 3, 4, 5, 6]

arr = [4, 5, 6]; // resetting the array

arr.unshift(1);
arr.unshift(2);
arr.unshift(3);

console.log(arr);
// [3, 2, 1, 4, 5, 6]

Die Methode unshift() ist generisch. Sie setzt lediglich voraus, dass der this-Wert eine length-Eigenschaft und Eigenschaften mit ganzzahligen Schlüsseln besitzt. Obwohl Strings ebenfalls array-ähnlich sind, eignet sich diese Methode nicht für sie, da Strings unveränderlich sind.

Beispiele

unshift() verwenden

const arr = [1, 2];

arr.unshift(0); // result of the call is 3, which is the new array length
// arr is [0, 1, 2]

arr.unshift(-2, -1); // the new array length is 5
// arr is [-2, -1, 0, 1, 2]

arr.unshift([-4, -3]); // the new array length is 6
// arr is [[-4, -3], -2, -1, 0, 1, 2]

arr.unshift([-7, -6], [-5]); // the new array length is 8
// arr is [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

unshift() für Objekte aufrufen, die keine Arrays sind

Die Methode unshift() liest die length-Eigenschaft von this. Sie verschiebt alle Indizes im Bereich von 0 bis length - 1 um die Anzahl der Argumente nach rechts (indem sie deren Werte um diese Anzahl erhöht). Anschließend belegt sie die Indizes ab 0 mit den an unshift() übergebenen Argumenten. Zuletzt setzt sie length auf die bisherige Länge zuzüglich der Anzahl der vorangestellten Elemente.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  2: 4,
};
Array.prototype.unshift.call(arrayLike, 1, 2);
console.log(arrayLike);
// { '0': 1, '1': 2, '4': 4, length: 5, unrelated: 'foo' }

const plainObj = {};
// There's no length property, so the length is 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill für Array.prototype.unshift in core-js mit Korrekturen für diese Methode
• Polyfill für Array.prototype.unshift von es-shims
• Leitfaden zu indizierten Sammlungen
• Array
• Array.prototype.push()
• Array.prototype.pop()
• Array.prototype.shift()
• Array.prototype.concat()
• Array.prototype.splice()