Array.prototype.copyWithin()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.
Die copyWithin() Methode von Array Instanzen kopiert einen Teil dieses Arrays oberflächlich an einen anderen Ort innerhalb desselben Arrays und gibt dieses Array zurück, ohne seine Länge zu verändern.
Probieren Sie es aus
const array1 = ["a", "b", "c", "d", "e"];
// Copy to index 0 the element at index 3
console.log(array1.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(array1.copyWithin(1, 3));
// Expected output: Array ["d", "d", "e", "d", "e"]
Syntax
copyWithin(target, start)
copyWithin(target, start, end)
Parameter
target-
Nullbasierter Index, an dem die Sequenz kopiert werden soll, zu einem ganzzahligen Wert umgewandelt. Dies entspricht dem Ort, an den das Element bei
startkopiert wird, und alle Elemente zwischenstartundendwerden auf nachfolgende Indizes kopiert.- Ein negativer Index zählt vom Ende des Arrays rückwärts — 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 vonarray.lengthkopiert (mit anderen Worten:copyWithin()verlängert nie das Array).
- Ein negativer Index zählt vom Ende des Arrays rückwärts — wenn
start-
Nullbasierter Index, von dem aus mit dem Kopieren der Elemente begonnen werden soll, zu einem ganzzahligen Wert umgewandelt.
- Ein negativer Index zählt vom Ende des Arrays rückwärts — 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 rückwärts — wenn
endOptional-
Nullbasierter Index, bis zu dem die Elemente kopiert werden sollen, zu einem ganzzahligen Wert umgewandelt.
copyWithin()kopiert bis, aber nicht einschließlichend.- Ein negativer Index zählt vom Ende des Arrays rückwärts — wenn
-array.length <= end < 0, wirdend + array.lengthverwendet. - Wenn
end < -array.length, wird0verwendet. - Wenn
end >= array.lengthoderendweggelassen oderundefinedist, wirdarray.lengthverwendet, wodurch alle Elemente bis zum Ende kopiert werden. - Wenn
endeine Position vor oder an der Position impliziert, diestartimpliziert, wird nichts kopiert.
- Ein negativer Index zählt vom Ende des Arrays rückwärts — wenn
Rückgabewert
Das modifizierte Array.
Beschreibung
Die copyWithin() Methode funktioniert ähnlich wie memmove in C und C++ und ist eine leistungsstarke Methode, um die Daten eines Array zu verschieben. Dies gilt insbesondere für die TypedArray Methode mit demselben Namen. Die Sequenz wird als eine Operation kopiert und eingefügt; die eingefügte Sequenz wird die kopierten Werte haben, selbst wenn sich die Kopier- und Einfügeregion überlappen.
Da undefined zu 0 wird, wenn es in einen ganzzahligen Wert umgewandelt wird, hat das Auslassen des start-Parameters denselben Effekt wie die Übergabe von 0, was das gesamte Array an die Zielposition kopiert, ähnlich einer Rechtsverschiebung, bei der die rechte Grenze abgeschnitten und die linke Grenze dupliziert wird. Dieses Verhalten kann Leser Ihres Codes verwirren, deshalb sollten Sie 0 explizit als start übergeben.
console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3]; move all elements to the right by 2 positions
Die copyWithin() Methode ist eine mutierende Methode. Sie verändert nicht die Länge von this, aber sie ändert den Inhalt von this und erstellt neue Eigenschaften oder löscht bestehende Eigenschaften, falls notwendig.
Die copyWithin() Methode bewahrt leere Slots. Wenn der zu kopierende Bereich spärlich ist, werden die leeren Slots in den entsprechenden neuen Indizes gelöscht und werden ebenfalls leere Slots.
Die copyWithin() Methode ist generisch. Sie erwartet nur, dass der this Wert eine length Eigenschaft und integer-basierten Schlüssel hat. Obwohl Zeichenketten auch array-ähnlich sind, ist diese Methode nicht geeignet, auf ihnen angewendet zu werden, da Zeichenketten unveränderlich sind.
Beispiele
Verwendung von copyWithin()
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]
Verwendung von copyWithin() auf spärlichen Arrays
copyWithin() wird leere Slots weiterleiten.
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]
Aufrufen von copyWithin() auf Nicht-Array-Objekte
Die copyWithin() Methode liest die length Eigenschaft von this und manipuliert dann die beteiligten 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
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-array.prototype.copywithin |