此頁面由社群從英文翻譯而來。了解更多並加入 MDN Web Docs 社群。
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 2015年9月.
Array 實體的copyWithin() 方法會將陣列中的部分元素進行淺複製，並將其放置於陣列內的另一個位置，同時返回該陣列，但不改變其長度。
嘗試一下
const array1 = ["a", "b", "c", "d", "e"];// 將索引 3 的元素複製到索引 0console.log(array1.copyWithin(0, 3, 4));// 預期輸出：Array ["d", "b", "c", "d", "e"]// 將索引 3 到結尾的所有元素複製到索引 1console.log(array1.copyWithin(1, 3));// 預期輸出：Array ["d", "d", "e", "d", "e"]語法
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未提供或為undefined，則使用array.length，使其複製至結尾。 - 若
end所對應的位置在start所對應的位置之前或相同，則不會複製任何內容。
- 負數索引會從陣列末尾開始計算 — 若
回傳值
被修改的陣列。
描述
copyWithin() 方法類似於 C 和 C++ 的memmove，它是一種高效能的方法，可用來移動Array 的資料。這在TypedArray 方法中尤其適用。該方法會將選定的序列一次性複製並貼上，即使複製區域與貼上區域重疊，貼上的序列仍然會保留已複製的值。
由於undefined 轉換為整數時會變為0，因此省略start 參數的效果與傳入0 相同，這會導致整個陣列被複製到目標位置，相當於向右位移，並裁剪右邊界、重複左邊界。此行為可能會讓你的程式碼讀者感到困惑，因此建議顯式傳入0 作為start。
console.log([1, 2, 3, 4, 5].copyWithin(2));// [1, 2, 1, 2, 3]；將所有元素向右移動 2 個位置copyWithin() 方法是一個可變異方法。它不會改變this 的長度，但會改變this 的內容，並在必要時新增或刪除屬性。
copyWithin() 方法會保留空槽。如果被複製的區域是稀疏陣列，則空槽對應的新索引會被刪除，並仍然為空槽。
copyWithin() 方法是通用的。它只要求this 具有length 屬性及整數鍵屬性。雖然字串也類似陣列，但此方法不適用於字串，因為字串是不可變的。
範例
使用 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]在稀疏陣列上使用 copyWithin()
copyWithin() 會傳播空槽。
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]在非陣列物件上調用 copyWithin()
copyWithin() 方法會讀取this 的length 屬性，並操作其中的整數索引。
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 |