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 flach einen Teil dieses Arrays an eine andere Position im gleichen Array und gibt dieses Array zurück, ohne seine Länge zu ä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, in eine ganze Zahl umgewandelt. Dies entspricht dem Ort, an den das Element bei
startkopiert wird, und alle Elemente zwischenstartundendwerden an nachfolgende 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 nachstartpositioniert ist, erfolgt das Kopieren nur bis zum Ende vonarray.length(mit anderen Worten,copyWithin()verlängert das Array niemals).
- Ein negativer Index zählt vom Ende des Arrays zurück — wenn
start-
Nullbasierter Index, ab dem das Kopieren von Elementen beginnen soll, in eine ganze Zahl 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, an dem das Kopieren von Elementen enden soll, in eine ganze Zahl umgewandelt.
copyWithin()kopiert bis, aber nicht einschließlichend.- 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.lengthoderendweggelassen oderundefinedist, wirdarray.lengthverwendet, sodass alle Elemente bis zum Ende kopiert werden. - Wenn
endauf eine Position vor oder an der Position verweist, diestartimpliziert, wird nichts kopiert.
- Ein negativer Index zählt vom Ende des Arrays zurück — wenn
Rückgabewert
Das modifizierte Array.
Beschreibung
Die Methode copyWithin() 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 Methode TypedArray mit demselben Namen. Die Sequenz wird als eine Operation kopiert und eingefügt; die eingefügte Sequenz enthält die kopierten Werte, selbst wenn sich die Kopier- und Einfügebereiche überschneiden.
Da undefined bei der Umwandlung in eine ganze Zahl zu 0 wird, hat das Weglassen des start-Parameters den gleichen Effekt wie die Übergabe von 0, wodurch das gesamte Array an die Zielposition kopiert wird, was einem Rechtsschieben entspricht, bei dem die rechte Grenze abgeschnitten und die linke Grenze dupliziert wird. Dieses Verhalten kann Leser Ihres Codes verwirren, daher sollten Sie 0 als start explizit ü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 Methode copyWithin() ist eine verändernde Methode. Sie ändert nicht die Länge von this, aber sie wird den Inhalt von this ändern und neue Eigenschaften erstellen oder vorhandene Eigenschaften bei Bedarf löschen.
Die Methode copyWithin() behält leere Slots bei. Wenn der zu kopierende Bereich dünn besetzt ist, werden die entsprechenden neuen Indizes der leeren Slots gelöscht und werden ebenfalls zu leeren Slots.
Die Methode copyWithin() ist generisch. Sie erwartet nur, dass der this-Wert eine length-Eigenschaft und ganzzahlige Schlüssel-Eigenschaften hat. Obwohl Zeichenfolgen auch array-ähnlich sind, ist diese Methode nicht geeignet, um auf sie angewendet zu werden, da Zeichenfolgen 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() bei dünn besetzten Arrays
copyWithin() wird leere Slots übertragen.
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]
Aufruf von copyWithin() bei Nicht-Array-Objekten
Die Methode copyWithin() 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 |