Array.prototype.copyWithin()
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit September 2015 browserübergreifend verfügbar.
Die Methode copyWithin() von Array-Instanzen kopiert einen Teil des Arrays als flache Kopie an eine andere Stelle desselben Arrays und gibt das Array zurück, ohne seine Länge zu ändern.
Probieren Sie es aus
const array = ["a", "b", "c", "d", "e"];
// Copy to index 0 the element at index 3
console.log(array.copyWithin(0, 3, 4));
// Expected output: Array ["d", "b", "c", "d", "e"]
// Copy to index 1 all elements from index 3 to the end
console.log(array.copyWithin(1, 3));
// Expected output: Array ["d", "d", "e", "d", "e"]
Syntax
copyWithin(target, start)
copyWithin(target, start, end)
Parameter
target-
Nullbasierter Index, an den die Sequenz kopiert werden soll, in eine Ganzzahl umgewandelt. An diese Position wird das Element bei
startkopiert; alle Elemente zwischenstartundendwerden an die folgenden Indizes kopiert.- Ein negativer Index zählt vom Ende des Arrays zurück – wenn
-array.length <= target < 0, wirdtarget + array.lengthverwendet. - Wenn
target < -array.length, wird0verwendet. - Wenn
target >= array.length, wird nichts kopiert. - Wenn
targetnach der Normalisierung hinterstartliegt, wird nur bis zum Ende des Arrays kopiert (mit anderen Worten:copyWithin()verlängert das Array nie).
- Ein negativer Index zählt vom Ende des Arrays zurück – wenn
start-
Nullbasierter Index, ab dem Elemente kopiert werden, in eine Ganzzahl umgewandelt.
- Ein negativer Index zählt vom Ende des Arrays zurück – wenn
-array.length <= start < 0, wirdstart + array.lengthverwendet. - Wenn
start < -array.length, wird0verwendet. - Wenn
start >= array.length, wird nichts kopiert.
- Ein negativer Index zählt vom Ende des Arrays zurück – wenn
endOptional-
Nullbasierter Index, bis zu dem Elemente kopiert werden, in eine Ganzzahl umgewandelt.
copyWithin()kopiert bis unmittelbar vorend.- Ein negativer Index zählt vom Ende des Arrays zurück – wenn
-array.length <= end < 0, wirdend + array.lengthverwendet. - Wenn
end < -array.length, wird0verwendet. - Wenn
end >= array.lengthoderendausgelassen wird oderundefinedist, wirdarray.lengthverwendet. Dadurch werden alle Elemente bis zum Ende kopiert. - Wenn die durch
endbezeichnete Position vor oder an der durchstartbezeichneten Position liegt, wird nichts kopiert.
- Ein negativer Index zählt vom Ende des Arrays zurück – wenn
Rückgabewert
Das veränderte Array.
Beschreibung
Die Methode copyWithin() funktioniert ähnlich wie memmove in C und C++ und ermöglicht es, die Daten eines Array mit hoher Leistung zu verschieben. Dies gilt insbesondere für die gleichnamige Methode von TypedArray. Die Sequenz wird in einem einzigen Vorgang kopiert und eingefügt. Die eingefügte Sequenz enthält auch dann die kopierten Werte, wenn sich Quell- und Zielbereich überschneiden.
Da undefined bei der Umwandlung in eine Ganzzahl zu 0 wird, hat das Weglassen des Parameters start dieselbe Wirkung wie die Übergabe von 0: Das gesamte Array wird an die Zielposition kopiert. Dies entspricht einer Verschiebung nach rechts, bei der Elemente am rechten Rand wegfallen und die Elemente am linken Rand dupliziert werden. Dieses Verhalten kann Leser Ihres Codes verwirren. Übergeben Sie daher besser ausdrücklich 0 als start.
console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3]; move all elements to the right by 2 positions
Die Methode copyWithin() verändert das Array. Sie ändert die Länge von this nicht, verändert aber dessen Inhalt und erstellt bei Bedarf neue Eigenschaften oder löscht vorhandene Eigenschaften.
Die Methode copyWithin() erhält leere Einträge. Wenn der Quellbereich dünn besetzt ist, werden die entsprechenden neuen Indizes der leeren Einträge gelöscht und sind ebenfalls leer.
Die Methode copyWithin() ist generisch. Sie setzt lediglich voraus, dass der Wert von this eine length-Eigenschaft und Eigenschaften mit ganzzahligen Schlüsseln hat. Obwohl Strings ebenfalls Array-ähnlich sind, eignet sich diese Methode nicht für sie, da Strings unveränderlich sind.
Beispiele
copyWithin() verwenden
console.log([1, 2, 3, 4, 5].copyWithin(0, 3));
// [4, 5, 3, 4, 5]
console.log([1, 2, 3, 4, 5].copyWithin(0, 3, 4));
// [4, 2, 3, 4, 5]
console.log([1, 2, 3, 4, 5].copyWithin(-2, -3, -1));
// [1, 2, 3, 3, 4]
copyWithin() mit dünn besetzten Arrays verwenden
copyWithin() überträgt auch leere Einträge.
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]
copyWithin() für Objekte aufrufen, die keine Arrays sind
Die Methode copyWithin() liest die length-Eigenschaft von this und bearbeitet anschließend die betroffenen ganzzahligen Indizes.
const arrayLike = {
length: 5,
3: 1,
};
console.log(Array.prototype.copyWithin.call(arrayLike, 0, 3));
// { '0': 1, '3': 1, length: 5 }
console.log(Array.prototype.copyWithin.call(arrayLike, 3, 1));
// { '0': 1, length: 5 }
// The '3' property is deleted because the copied source is an empty slot
Spezifikationen
| Spezifikation |
|---|
| ECMAScript® 2027 Language Specification # sec-array.prototype.copywithin |