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 2016.

Array 實體的 copyWithin() 方法會將陣列中的部分元素進行淺複製，並將其放置於陣列內的另一個位置，同時返回該陣列，但不改變其長度。

嘗試一下

const array1 = ["a", "b", "c", "d", "e"];

// 將索引 3 的元素複製到索引 0
console.log(array1.copyWithin(0, 3, 4));
// 預期輸出：Array ["d", "b", "c", "d", "e"]

// 將索引 3 到結尾的所有元素複製到索引 1
console.log(array1.copyWithin(1, 3));
// 預期輸出：Array ["d", "d", "e", "d", "e"]

語法

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

參數

target

要複製序列至的以零為基底的索引，會轉換為整數。這對應到 start 位置的元素將被複製至 target，而 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 選擇性

要結束複製元素的以零為基底的索引，會轉換為整數。copyWithin() 會複製至 end 之前的元素，但不包含 end。

  • 負數索引會從陣列末尾開始計算 — 若 -array.length <= end < 0，則使用 end + array.length。
  • 若 end < -array.length，則使用 0。
  • 若 end >= array.length 或未提供 end，則使用 array.length，使其複製至結尾。
  • 若 end 所對應的位置在 start 所對應的位置之前或相同，則不會複製任何內容。

回傳值

被修改的陣列。

描述

copyWithin() 方法類似於 C 和 C++ 的 memmove，它是一種高效能的方法，可用來移動 Array 的資料。這在 TypedArray 方法中尤其適用。該方法會將選定的序列一次性複製並貼上，即使複製區域與貼上區域重疊，貼上的序列仍然會保留已複製的值。

由於 undefined 轉換為整數時會變為 0，因此省略 start 參數的效果與傳入 0 相同，這會導致整個陣列被複製到目標位置，相當於向右位移，並裁剪右邊界、重複左邊界。此行為可能會讓你的程式碼讀者感到困惑，因此建議顯式傳入 0 作為 start。

js
console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3]；將所有元素向右移動 2 個位置

copyWithin() 方法是一個可變異方法。它不會改變 this 的長度，但會改變 this 的內容，並在必要時新增或刪除屬性。

copyWithin() 方法會保留空槽。如果被複製的區域是稀疏陣列，則空槽對應的新索引會被刪除，並仍然為空槽。

copyWithin() 方法是通用的。它只要求 this 具有 length 屬性及整數鍵屬性。雖然字串也類似陣列，但此方法不適用於字串，因為字串是不可變的。

範例

使用 copyWithin()

js
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()

copyWithin() 會傳播空槽。

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

在非陣列物件上調用 copyWithin()

copyWithin() 方法會讀取 this 的 length 屬性，並操作其中的整數索引。

js
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 }
// 屬性「3」被刪除，因為複製來源是空槽

規範

Specification
ECMAScript® 2026 Language Specification
# sec-array.prototype.copywithin

瀏覽器相容性

參見