---
title: Array.prototype.copyWithin()
slug: Web/JavaScript/Reference/Global_Objects/Array/copyWithin
tags:
  - Array
  - ECMAScript 2015
  - JavaScript
  - Method
  - Prototype
  - Reference
  - polyfill
translation_of: Web/JavaScript/Reference/Global_Objects/Array/copyWithin
---
<div>{{JSRef}}</div>

<p><code><strong>copyWithin()</strong></code> 方法會對陣列的一部分進行淺拷貝至同一陣列的另一位置並回傳此陣列，而不修改其大小。</p>

<div>{{EmbedInteractiveExample("pages/js/array-copywithin.html")}}</div>



<h2 id="語法">語法</h2>

<pre class="syntaxbox"><var>arr</var>.copyWithin(<var>target</var>)
<var>arr</var>.copyWithin(<var>target</var>, <var>start</var>)
<var>arr</var>.copyWithin(<var>target</var>, <var>start</var>, <var>end</var>)
</pre>

<h3 id="參數">參數</h3>

<dl>
 <dt><code>target</code></dt>
 <dd>要複製序列（sequence）至該位置的索引（起始為 0）。若為負數，<code>target</code> 將會自陣列末項開始計算。</dd>
 <dd>假如 <code>target</code> 大於等於 <code>arr.length</code>，則沒有項目會被複製。如果 <code>target</code> 的索引在 <code>start</code> 之後，則拷貝的序列將會被修剪以符合 <code>arr.length</code>。</dd>
 <dt><code>start</code> {{optional_inline}}</dt>
 <dd>開始拷貝的起始元素索引（起始為 0）。若為負數，<code>start</code> 將會自陣列末項開始計算。</dd>
 <dd>如果省略 <code>start</code>，<code>copyWithin</code> 將會自陣列首項開始複製（預設為 0）。</dd>
 <dt><code>end</code> {{optional_inline}}</dt>
 <dd>結束拷貝的結尾元素索引（起始為 0）。<code>copyWithin</code> 會拷貝至此索引，但不包含 <code>end</code>。若為負數，<code>end</code> 將會自陣列末項開始計算。</dd>
 <dd>如果省略 <code>end</code>，<code>copyWithin</code> 將會一路拷貝至陣列末項（預設至 <code>arr.length</code>）。</dd>
</dl>

<h3 id="回傳值">回傳值</h3>

<p>被修改後的陣列。</p>

<h2 id="描述">描述</h2>

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

<p>The <code>copyWithin</code> function is intentionally <em>generic</em>, it does not require that its this value be an {{jsxref("Array")}} object.</p>

<p>The <code>copyWithin</code> method is a mutable method. It does not alter the length of <code>this</code>, but will change its content and create new properties if necessary.</p>

<h2 id="範例">範例</h2>

<pre class="brush: js">[1, 2, 3, 4, 5].copyWithin(-2);
// [1, 2, 3, 1, 2]

[1, 2, 3, 4, 5].copyWithin(0, 3);
// [4, 5, 3, 4, 5]

[1, 2, 3, 4, 5].copyWithin(0, 3, 4);
// [4, 2, 3, 4, 5]

[1, 2, 3, 4, 5].copyWithin(-2, -3, -1);
// [1, 2, 3, 3, 4]

[].copyWithin.call({length: 5, 3: 1}, 0, 3);
// {0: 1, 3: 1, length: 5}

// ES2015 Typed Arrays are subclasses of Array
var i32a = new Int32Array([1, 2, 3, 4, 5]);

i32a.copyWithin(0, 2);
// Int32Array [3, 4, 5, 4, 5]

// On platforms that are not yet ES2015 compliant:
[].copyWithin.call(new Int32Array([1, 2, 3, 4, 5]), 0, 3, 4);
// Int32Array [4, 2, 3, 4, 5]
</pre>

<h2 id="Polyfill">Polyfill</h2>

<pre class="brush: js">if (!Array.prototype.copyWithin) {
  Array.prototype.copyWithin =
  // Array: Number[, Number[, Number]]
  function copyWithin(target, start, stop) {
    var positiveT = target &gt;= 0,
        positiveS = (start = start | 0) &gt;= 0,
        length    = this.length,
        zero      = 0,
        r         = function() {return ((+new Date) * Math.random()).toString(36)},
        delimiter = "\b" + r() + "-" + r() + "-" + r() + "\b",
        hold;

    stop = stop || this.length;
    hold = this.slice.apply(this,
      positiveT?
        [start, stop]:
      positiveS?
        [start, -target]:
      [start])
    .join(delimiter);

    return this.splice.apply(this,
      positiveT?
        [target, stop - start, hold]:
      positiveS?
        [target, stop, hold]:
      [target, start, hold]),
            this.join(delimiter).split(delimiter).slice(zero, length);
  }
}
</pre>

<h2 id="規範">規範</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('ES2015', '#sec-array.prototype.copywithin', 'Array.prototype.copyWithin')}}</td>
   <td>{{Spec2('ES2015')}}</td>
   <td>Initial definition.</td>
  </tr>
  <tr>
   <td>{{SpecName('ES2016', '#sec-array.prototype.copywithin', 'Array.prototype.copyWithin')}}</td>
   <td>{{Spec2('ES2016')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-array.prototype.copywithin', 'Array.prototype.copyWithin')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="瀏覽器相容性">瀏覽器相容性</h2>

<div>


<p>{{Compat("javascript.builtins.Array.copyWithin")}}</p>
</div>

<h2 id="參見">參見</h2>

<ul>
 <li>{{jsxref("Array")}}</li>
</ul>