Array.prototype.unshift()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die unshift()-Methode von Array-Instanzen fügt die angegebenen Elemente am Anfang eines Arrays hinzu und gibt die neue Länge des Arrays zurück.

Probieren Sie es aus

Syntax

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

Parameter

element1, …, elementN

Die Elemente, die zum Anfang des arr hinzugefügt werden sollen.

Rückgabewert

Die neue length-Eigenschaft des Objekts, auf dem die Methode aufgerufen wurde.

Beschreibung

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

Array.prototype.push() hat ein ähnliches Verhalten wie unshift(), wird jedoch am Ende eines Arrays angewendet.

Bitte beachten Sie, dass wenn mehrere Elemente als Parameter übergeben werden, diese in der Reihenfolge, in der sie übergeben wurden, als Block am Anfang des Objekts eingefügt werden. Deshalb führt der Aufruf von unshift() mit n Argumenten einmal oder das n-fache Aufrufen mit 1 Argument (zum Beispiel in einer Schleife) nicht zu den gleichen Ergebnissen.

Beispiel:

js
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 unshift()-Methode ist generisch. Sie erwartet nur, dass der this-Wert eine length-Eigenschaft und integer-indizierte Eigenschaften hat. Obwohl Strings ebenfalls array-ähnlich sind, ist diese Methode nicht für sie geeignet, da Strings unveränderlich sind.

Beispiele

Verwendung von unshift()

js
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 ]

Aufruf von unshift() auf Nicht-Array-Objekten

Die unshift()-Methode liest die length-Eigenschaft von this. Sie verschiebt alle Indizes im Bereich von 0 bis length - 1 nach rechts um die Anzahl der Argumente (erhöht deren Werte um diese Zahl). Dann setzt sie jeden Index beginnend bei 0 mit den an unshift() übergebenen Argumenten. Schließlich setzt sie die length auf die vorherige Länge plus die Anzahl der hinzugefügten Elemente.

js
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

Specification
ECMAScript Language Specification
# sec-array.prototype.unshift

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch