Array.prototype.copyWithin()

¥Syntax

copyWithin(target, start)
copyWithin(target, start, end)

¥Parameters

target

将序列复制到的从零开始的索引，转换为整数。这对应于 start 处的元素将被复制到的位置，并且 start 和 end 之间的所有元素都将复制到后续索引。

• 负索引从数组末尾开始倒数 — 如果使用 -array.length <= target < 0、target + array.length。
• 如果使用 target < -array.length、0。
• 如果是 target >= array.length，则不复制任何内容。
• 如果标准化后 target 位于 start 之后，则复制只会发生到 array.length 末尾（换句话说，copyWithin() 永远不会扩展数组）。

start

从零开始的索引，从该位置开始复制元素，转换为整数。

• 负索引从数组末尾开始倒数 — 如果使用 -array.length <= start < 0、start + array.length。
• 如果使用 start < -array.length、0。
• 如果是 start >= array.length，则不复制任何内容。

end Optional

结束从 转换为整数 复制元素的从零开始的索引。copyWithin() 复制直至但不包括 end。

• 负索引从数组末尾开始倒数 — 如果使用 -array.length <= end < 0、end + array.length。
• 如果使用 end < -array.length、0。
• 如果省略 end >= array.length 或 end，则使用 array.length，导致复制直到末尾的所有元素。
• 如果 end 暗示的位置在 start 暗示的位置之前或处，则不会复制任何内容。

¥Return value

修改后的数组。

¥The modified array.

¥Description

copyWithin() 方法的工作方式类似于 C 和 C++ 的 memmove，并且是一种用于移位 Array 数据的高性能方法。这尤其适用于同名的 TypedArray 方法。复制和粘贴序列作为一项操作；即使复制和粘贴区域重叠，粘贴的序列也将具有复制的值。

¥The copyWithin() method works like C and C++'s memmove, and is a high-performance method to shift the data of an Array. This especially applies to the TypedArray method of the same name. The sequence is copied and pasted as one operation; the pasted sequence will have the copied values even when the copy and paste region overlap.

因为 undefined 转为整数时就变成了 0，所以省略 start 参数和传递 0 效果一样，将整个数组复制到目标位置，相当于右移，右边界被剪掉，左边界被复制 。此行为可能会让代码的读者感到困惑，因此你应该显式地将 0 作为 start 传递。

¥Because undefined becomes 0 when converted to an integer, omitting the start parameter has the same effect as passing 0, which copies the entire array to the target position, equivalent to a right shift where the right boundary is clipped off and the left boundary is duplicated. This behavior may confuse readers of your code, so you should explicitly pass 0 as start instead.

console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3]; move all elements to the right by 2 positions

copyWithin() 方法是 变异法 方法。它不会更改 this 的长度，但会更改 this 的内容并创建新属性或删除现有属性（如有必要）。

¥The copyWithin() method is a mutating method. It does not alter the length of this, but it will change the content of this and create new properties or delete existing properties, if necessary.

copyWithin() 方法保留空槽。如果要复制的区域是 sparse，则空槽对应的新索引是 deleted，也成为空槽。

¥The copyWithin() method preserves empty slots. If the region to be copied from is sparse, the empty slots' corresponding new indices are deleted and also become empty slots.

copyWithin() 方法是 generic。它只期望 this 值具有 length 属性和整数键控属性。虽然字符串也是类似数组的，但此方法不适合应用于它们，因为字符串是不可变的。

¥The copyWithin() method is generic. It only expects the this value to have a length property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.

¥Examples

¥Using 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]

¥Using copyWithin() on sparse arrays

copyWithin() 将传播空槽。

¥copyWithin() will propagate empty slots.

console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]

¥Calling copyWithin() on non-array objects

copyWithin() 方法读取 this 的 length 属性，然后操作涉及的整数索引。

¥The copyWithin() method reads the length property of this and then manipulates the integer indices involved.

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

¥See also

• core-js 中 Array.prototype.copyWithin 的 Polyfill
• 索引集合 指南
• Array
• TypedArray.prototype.copyWithin()