Array.prototype.toSpliced() — Methode · JavaScript-Referenz

Signatur

Array.prototype.toSpliced(start, skipCount, ...items)

Beschreibung

toSpliced() ist die kopierende Version von splice(). Die Methode kann an beliebiger Stelle Elemente entfernen, ersetzen oder einfügen, ändert das ursprüngliche Array aber nicht. Stattdessen liefert sie ein neues Array mit dem Ergebnis.

Nützlich ist das überall dort, wo Daten unveränderlich bleiben sollen, zum Beispiel beim State-Management in React, Vue oder Redux, in reinen Funktionen oder wenn mehrere Programmteile dasselbe Array verwenden. Früher brauchte man dafür Kombinationen wie [...arr.slice(0, i), neu, ...arr.slice(i + 1)]. Diese Konstrukte lassen sich jetzt durch einen einzigen, gut lesbaren Aufruf ersetzen.

Wichtig ist der Unterschied beim Rückgabewert: splice() gibt die entfernten Elemente zurück, toSpliced() dagegen das neue, geänderte Array. Die entfernten Elemente bekommt man mit toSpliced() nicht direkt. Dafür verwendet man vorher slice().

Lücken in dünn besetzten Arrays (sparse arrays) werden im Ergebnis zu undefined. Das neue Array ist also nie dünn besetzt. Die Methode ist generisch und funktioniert auch mit Array-ähnlichen Objekten, die eine length-Eigenschaft haben.

Parameter

Name	Typ	Default	Beschreibung
$start Pflicht	number		Index (ab 0), an dem die Änderung beginnt. Negative Werte zählen vom Ende (`-1` ist das letzte Element). Ist der Wert kleiner als `-length`, wird `0` verwendet. Ist er größer oder gleich `length`, wird am Ende eingefügt. Fehlt der Parameter, wird `0` angenommen.
$skipCount	number	array.length - start	Anzahl der Elemente, die ab `start` entfernt werden. Fehlt der Parameter (und fehlen auch `items`), wird alles ab `start` entfernt. Bei `0` oder negativen Werten wird nichts entfernt.
$...items	any		Elemente, die ab `start` eingefügt werden. Ohne Angabe werden nur Elemente entfernt.

Rückgabewert

Typ

Array

Beschreibung

Ein neues Array: alle Elemente vor start, dann die items, dann die restlichen Elemente nach den übersprungenen. Das ursprüngliche Array bleibt unverändert.

Beispiele

Entfernen, Ersetzen und Einfügen ohne Nebenwirkungen

const monate = ['Jan', 'Feb', 'Apr', 'Mai'];

// Einfügen: an Index 2 nichts entfernen, 'Mär' einfügen
const eingefuegt = monate.toSpliced(2, 0, 'Mär');
console.log(eingefuegt);

// Ersetzen: an Index 1 ein Element durch zwei neue ersetzen
const ersetzt = eingefuegt.toSpliced(1, 1, 'Februar', 'Feb2');
console.log(ersetzt);

// Entfernen: ab Index 3 zwei Elemente löschen
const gekuerzt = eingefuegt.toSpliced(3, 2);
console.log(gekuerzt);

// Original bleibt unverändert
console.log(monate);

['Jan', 'Feb', 'Mär', 'Apr', 'Mai'] ['Jan', 'Februar', 'Feb2', 'Mär', 'Apr', 'Mai'] ['Jan', 'Feb', 'Mär'] ['Jan', 'Feb', 'Apr', 'Mai']

Unveränderliches State-Update (z. B. React/Redux)

const todos = [
  { id: 1, text: 'Einkaufen' },
  { id: 2, text: 'Code-Review' },
  { id: 3, text: 'Sport' }
];

// Todo per ID entfernen, ohne den alten State zu verändern
const removeTodo = (list, id) => {
  const index = list.findIndex((t) => t.id === id);
  return index === -1 ? list : list.toSpliced(index, 1);
};

const neuerState = removeTodo(todos, 2);
console.log(neuerState.map((t) => t.text));
console.log(todos.length);
console.log(neuerState !== todos);

['Einkaufen', 'Sport'] 3 true

Negativer Index und Unterschied zu splice()

const zahlen = [1, 2, 3, 4, 5];

// Die letzten beiden Elemente durch 99 ersetzen
console.log(zahlen.toSpliced(-2, 2, 99));

// splice() liefert dagegen die ENTFERNTEN Elemente und verändert das Original
const kopie = [...zahlen];
const entfernt = kopie.splice(-2, 2, 99);
console.log(entfernt);
console.log(kopie);

[1, 2, 3, 99] [4, 5] [1, 2, 3, 99]

Lücken werden zu undefined, Array-ähnliche Objekte

const duenn = [1, , 3, 4];
console.log(duenn.toSpliced(3, 1));

const arrayLike = { length: 3, 0: 'a', 1: 'b', 2: 'c' };
console.log(Array.prototype.toSpliced.call(arrayLike, 1, 1, 'x'));

[1, undefined, 3] ['a', 'x', 'c']

// Wichtig · Fallstricke

Anderer Rückgabewert als splice(): toSpliced() gibt das neue Array zurück, nicht die entfernten Elemente. Wer von splice() umstellt, übersieht das leicht.
Nur eine flache Kopie: Objekte im Array werden nicht geklont. Ändert man ein Objekt im neuen Array, ändert es sich auch im Original.
Ohne Argumente: arr.toSpliced() gibt eine unveränderte Kopie zurück. arr.toSpliced(0) gibt dagegen ein leeres Array zurück, weil dann alles ab Index 0 entfernt wird.
Sparse Arrays: Lücken werden im Ergebnis zu undefined. Das kann das Verhalten von forEach() oder in-Prüfungen verändern.
Typed Arrays: Anders als toSorted(), toReversed() und with() gibt es toSpliced() nicht auf TypedArray.prototype.
Kompatibilität: Verfügbar ab ES2023: Chrome/Edge 110, Firefox 115, Safari 16, Node.js 20. Für ältere Umgebungen gibt es ein Polyfill (z. B. core-js), oder man kombiniert slice() mit dem Spread-Operator.
Leistung: Jeder Aufruf legt ein vollständig neues Array an (O(n)). Bei vielen Änderungen an großen Arrays in engen Schleifen kann ein einmal kopiertes Array mit splice() schneller sein.

Siehe auch

Array.prototype.splice() Array.prototype.slice() Array.prototype.toSorted() Array.prototype.toReversed() Array.prototype.with() Array