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 Stelle im selben 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 Punkt, an dem das Element bei
startkopiert wird, und alle Elemente zwischenstartundendwerden an die nachfolgenden 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()erweitert das Array niemals).
- Ein negativer Index zählt vom Ende des Arrays zurück — wenn
start-
Nullbasierter Index, ab dem die Elemente kopiert werden sollen, 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, 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 zurück — wenn
Rückgabewert
Das modifizierte Array.
Beschreibung
Die copyWithin() Methode arbeitet wie memmove in C und C++ und ist eine leistungsstarke Methode zum Verschieben der Daten eines Array. Dies gilt insbesondere für die TypedArray Methode desselben Namens. 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 überlappen.
Da undefined beim Umwandeln in eine ganze Zahl zu 0 wird, hat das Weglassen des start Parameters denselben Effekt wie das Übergeben von 0, was das gesamte Array an die Zielposition kopiert, was einem Rechtsschiebepunkt entspricht, bei dem die rechte Grenze abgeschnitten und die linke Grenze dupliziert wird. Dieses Verhalten kann Leser Ihres Codes verwirren, daher 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 ändert nicht die Länge von this, wird jedoch den Inhalt von this ändern und bei Bedarf neue Eigenschaften erstellen oder vorhandene Eigenschaften löschen.
Die copyWithin() Methode bewahrt leere Plätze. Wenn der zu kopierende Bereich dünn besetzt ist, werden die leeren Plätzen in den neuen Indizes gelöscht und werden ebenfalls leere Plätze.
Die copyWithin() Methode ist generisch. Sie erwartet nur, dass der this Wert eine length Eigenschaft und ganzzahlenschlüsselbasierte Eigenschaften hat. Obwohl Strings ebenfalls array-ähnlich sind, ist diese Methode nicht geeignet, um auf sie angewendet zu werden, da Strings 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 dünn besiedelten Arrays
copyWithin() wird leere Plätze propagieren.
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]
Aufrufen von copyWithin() auf Objekten, die keine Arrays sind
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 |